#kubernetes#envoy-gateway#gateway-api#troubleshooting#status#debugging

Guide du status et du débogage d'Envoy Gateway : ce que veulent vraiment dire Accepted, ResolvedRefs et Programmed

7 min read

Le scénario d'ingénierie le plus pénible n'est pas un message d'erreur, c'est plutôt :

Vous avez appliqué le YAML, kubectl apply a réussi, mais le trafic ne circule toujours pas.

Si, à ce stade, vous ne faites que fixer spec, vous finirez par avoir l'impression de lire dans des feuilles de thé. La vraie information de diagnostic dans Gateway API vit dans status.

Cet article a un seul objectif : vous donner le chemin de débogage le plus court possible. Quand un Gateway, HTTPRoute ou Listener ne prend pas effet, vous saurez où regarder d'abord, au lieu de commencer immédiatement à douter du sens de l'univers.

Commencez ici : déboguez en lisant status, pas en changeant spec

Les commandes les plus utiles :

kubectl get gateway -A
kubectl get httproute -A
kubectl get grpcroute -A
kubectl describe gateway <name>
kubectl describe httproute <name>
kubectl get gateway <name> -o yaml
kubectl get httproute <name> -o yaml

Le but n'est pas de relire le YAML cent fois de plus, mais de vérifier si le contrôleur a réellement accepté votre configuration.

Voyez status comme le relevé de notes d'un examen :

  • spec est la copie que vous avez rendue
  • status est le résultat corrigé par le système

Ne regarder que ce que vous avez soumis, sans jamais vérifier la note, ce n'est pas du débogage, c'est juste du réconfort émotionnel.

Les trois conditions les plus importantes : maîtrisez-les et vous êtes couvert

Accepted

Cela indique généralement si la ressource a été acceptée par son parent. Pour une route, cela signifie souvent :

  • Si elle s'est correctement attachée au Gateway/listener visé
  • Si les règles comportent des conflits évidents ou une configuration invalide

Si Accepted vaut False, soupçonnez d'abord :

  • Des parentRefs pointant vers le mauvais Gateway ou listener
  • Des conditions de hostname/listener qui ne correspondent pas
  • Un listener qui rejette ce type de route
  • allowedRoutes qui vous bloque

ResolvedRefs

Cela indique si les objets référencés à l'intérieur de la ressource ont bien été résolus. Par exemple :

  • Le Service référencé dans backendRefs existe-t-il ?
  • Le Secret dans certificateRefs peut-il être référencé légalement ?
  • ReferenceGrant est-il bien configuré pour les références inter-namespace ?

Cette condition est extrêmement utile. Beaucoup d'échecs de configuration ne viennent pas d'une logique de routage erronée, mais d'éléments référencés qui n'existent tout simplement pas, ou auxquels vous n'avez pas le droit d'accéder.

Programmed

Cela indique généralement si la configuration a réellement été appliquée au niveau de l'implémentation. Pensez-y comme ceci :

  • Le contrôleur a accepté la configuration
  • Et il l'a poussée dans le plan de données ou l'infrastructure

Si Accepted vaut déjà True mais que le trafic ne circule toujours pas, c'est le moment où il devient utile de vérifier Programmed, l'adresse du Gateway, le status des listeners et les ressources Envoy sous-jacentes.

💡 Différentes ressources peuvent exposer des ensembles de conditions différents, mais Accepted, ResolvedRefs et Programmed sont le premier trio sur lequel construire votre intuition.

Le flux de débogage le plus court : cet ordre fonctionne généralement

Étape 1 : vérifier que le Gateway tourne réellement

kubectl get gateway -A
kubectl get gateway eg -o yaml

Vérifiez :

  • status.addresses contient-il une valeur ?
  • Y a-t-il des conditions anormales sur les listeners ?
  • Le hostname/protocole/port du listener correspond-il à ce que vous attendez ?

Si le Gateway n'a pas d'adresse, même le plus beau YAML de route n'est que de l'écriture créative.

Étape 2 : vérifier que la Route s'est bien attachée

kubectl get httproute -A
kubectl get httproute app-route -o yaml

Priorité à :

  • status.parents
  • Accepted
  • ResolvedRefs
  • observedGeneration

observedGeneration mérite qu'on y prête attention. S'il n'a pas rattrapé metadata.generation, le contrôleur n'a peut-être pas encore traité la dernière version de votre configuration.

Étape 3 : vérifier que les ressources référencées existent vraiment

Cette étape est plus souvent sautée que toutes les autres :

kubectl get svc -A
kubectl get secret -A
kubectl get referencegrant -A

Problèmes courants :

  • Le nom du service backend est faux
  • Le port est faux
  • Le Secret n'est pas dans le namespace que vous imaginez
  • La référence inter-namespace n'a pas de ReferenceGrant

Si ResolvedRefs vaut False, remontez la piste par ici.

Étape 4 : vérifier le plan de données et le contrôleur

Si les status du Gateway et de la Route semblent globalement corrects mais que le trafic ne circule toujours pas, allez plus loin :

kubectl get pods -n envoy-gateway-system
kubectl logs -n envoy-gateway-system deployment/envoy-gateway

À ce stade, vous ne déboguez plus "la règle a-t-elle été acceptée", vous vérifiez si le plan de contrôle et le plan de données fonctionnent normalement.

Si vous avez egctl installé, il peut vous aider à inspecter rapidement le status. Mais même sans lui, kubectl get/describe -o yaml permet de résoudre la plupart des problèmes.

Quatre patterns d'échec les plus courants

1. La route est correcte, mais ne s'est pas attachée au listener voulu

Symptômes :

  • Le YAML semble correct
  • Mais le trafic ne touche pas la règle

Vérifiez :

  • parentRefs.name
  • parentRefs.sectionName
  • Si le nom du listener du Gateway correspond exactement

Dans les setups multi-listeners, une simple faute de frappe dans sectionName suffit pour gaspiller toute une session de débogage.

2. Accepted réussit, mais ResolvedRefs échoue

Cela signifie généralement que la logique d'attachement est bonne, mais qu'un élément référencé pose problème. Causes les plus fréquentes :

  • Le Service backend n'existe pas
  • Le nom du Secret est incorrect
  • Référence inter-namespace sans autorisation

Ce type d'échec est particulièrement frustrant parce qu'il donne l'impression que vous êtes presque arrivé, alors qu'en réalité vous êtes encore bloqué à l'étape des références.

3. Le Gateway a des listeners, mais pas l'adresse attendue

Cela apparaît fréquemment dans les clusters locaux ou dans les environnements sans implémentation LoadBalancer. Ce n'est pas que Gateway API soit cassé, c'est simplement que l'infrastructure sous-jacente ne provisionne pas d'adresse externe.

Options :

  • Vérifier si le cluster possède la capacité LoadBalancer
  • Utiliser port-forward pour valider le chemin de routage

4. Le YAML a pris effet, mais les requêtes renvoient 404 / 503

À ce stade, ce n'est généralement pas un seul champ erroné, mais une chaîne cassée quelque part :

  • Mauvais header Host
  • Le path ne matche aucune règle
  • Le Pod backend n'est pas sain
  • Le selector du Service ne sélectionne aucun Pod

Les problèmes d'entrée ressemblent parfois à un échec du proxy, alors que le backend n'était tout simplement pas prêt. N'accusez pas tout de suite la couche proxy, elle en a déjà assez sur les épaules.

Résumé en une ligne

La manière la plus efficace de déboguer Gateway API n'est pas de modifier sans cesse le YAML, mais d'apprendre à lire status. Accepted vous dit si la demande a été prise en compte. ResolvedRefs vous dit si les références ont été résolues. Programmed vous dit si la configuration a réellement été appliquée. Examinez ces trois couches séparément et la vitesse de dépannage augmentera fortement.

Étape suivante

Cela termine la série de 10 articles sur Envoy Gateway. Si vous souhaitez revoir la carte complète de la série :

👉 Vue d'ensemble de la série