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

Manual de Status y Debugging de Envoy Gateway: Qué significan realmente Accepted, ResolvedRefs y Programmed

6 min read

El escenario de ingeniería más temido no es un mensaje de error — es:

Aplicaste el YAML, kubectl apply tuvo éxito, pero el tráfico sigue sin fluir.

Si en este punto solo te quedas mirando el spec, empezarás a sentir que estás leyendo el poso del café. La información diagnóstica real en Gateway API vive en status.

Este artículo tiene un solo objetivo: darte el camino de debugging más corto posible. Cuando un Gateway, HTTPRoute o Listener no surte efecto, sabrás dónde mirar primero — en lugar de cuestionarte de inmediato si el universo tiene sentido.

Empezar aquí: Depura leyendo status, no cambiando spec

Los comandos más útiles:

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

El objetivo no es releer el YAML cien veces más — es verificar si el controlador realmente aceptó tu configuración.

Piensa en status como una hoja de calificaciones de examen:

  • spec es la respuesta que enviaste
  • status es el resultado corregido por el sistema

Mirar solo lo que enviaste, sin revisar nunca la calificación — eso es solo consuelo emocional, no debugging.

Las tres conditions más importantes: domínalas y estarás cubierto

Accepted

Esto normalmente indica si el recurso fue aceptado por su padre. Para una ruta, suele significar:

  • Si se adjuntó correctamente al Gateway/listener previsto
  • Si las reglas tienen algún conflicto obvio o configuración inválida

Si Accepted es False, sospecha primero de:

  • parentRefs apuntando al Gateway o listener equivocado
  • Condiciones de hostname/listener que no coinciden
  • El listener rechazando este tipo de ruta
  • allowedRoutes bloqueándote

ResolvedRefs

Esto indica si los objetos referenciados dentro del recurso se resolvieron correctamente. Por ejemplo:

  • ¿Existe el Service referenciado en backendRefs?
  • ¿Puede referenciarse legalmente el Secret en certificateRefs?
  • ¿Está ReferenceGrant correctamente configurado para referencias entre namespaces?

Esta condition es extremadamente útil. Muchos fallos de configuración no son por lógica de enrutamiento incorrecta — son por cosas referenciadas que simplemente no existen, o a las que no tienes permiso de acceder.

Programmed

Esto normalmente indica si la configuración fue efectivamente aplicada en la capa de implementación. Piénsalo como:

  • El controlador aceptó la configuración
  • Y la envió al data plane o la infraestructura

Si Accepted ya es True pero el tráfico sigue sin fluir, es el momento en que vale la pena revisar Programmed, la dirección del Gateway, el estado de los listeners y los recursos de Envoy subyacentes.

💡 Distintos recursos pueden exponer diferentes conjuntos de conditions, pero Accepted, ResolvedRefs y Programmed son el primer grupo sobre el que conviene desarrollar intuición.

Flujo de debugging más corto: este orden suele funcionar

Paso 1: Verificar si el Gateway está realmente en ejecución

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

Verifica:

  • ¿Tiene status.addresses algún valor?
  • ¿Hay alguna condition de listener anormal?
  • ¿El hostname/protocol/port del listener coincide con lo que esperas?

Si el Gateway no tiene dirección, incluso el YAML de ruta más hermoso es solo escritura creativa.

Paso 2: Verificar si la ruta se adjuntó correctamente

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

Prioriza:

  • status.parents
  • Accepted
  • ResolvedRefs
  • observedGeneration

observedGeneration vale la pena vigilarlo. Si no ha alcanzado a metadata.generation, es posible que el controlador aún no haya procesado tu última versión de configuración.

Paso 3: Verificar si los recursos referenciados realmente existen

Este paso se omite con más frecuencia que cualquier otro:

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

Problemas comunes:

  • El nombre del servicio de backend es incorrecto
  • El puerto es incorrecto
  • El Secret no está en el namespace que crees
  • La referencia entre namespaces no tiene ReferenceGrant

Si ResolvedRefs es False, rastrea el problema siguiendo este camino.

Paso 4: Verificar el data plane y el controlador

Si el status del Gateway y de la ruta parecen más o menos correctos pero el tráfico sigue sin fluir, profundiza más:

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

En este punto ya no estás depurando "¿se aceptó la regla?" — estás verificando si el control plane y el data plane funcionan con normalidad.

Si tienes egctl instalado, puede ayudarte a inspeccionar el estado rápidamente. Pero incluso sin él, kubectl get/describe -o yaml puede resolver la mayoría de los problemas.

Los cuatro patrones de fallo más comunes

1. La ruta es correcta, pero no se adjuntó al listener previsto

Síntomas:

  • El YAML parece correcto
  • Pero el tráfico no está llegando a la regla

Comprueba:

  • parentRefs.name
  • parentRefs.sectionName
  • Si el nombre del listener del Gateway coincide exactamente

En configuraciones multi-listener, un solo error tipográfico en sectionName es suficiente para desperdiciar una sesión de debugging entera.

2. Accepted tiene éxito, pero ResolvedRefs falla

Esto suele significar que la lógica puede adjuntarse, pero algo referenciado tiene un problema. Causas más comunes:

  • El Service de backend no existe
  • El nombre del Secret es incorrecto
  • Referencia entre namespaces sin autorización

Lo más frustrante de este tipo de fallo es que parece que ya casi llegaste — pero en realidad está atascado en la capa de referencia.

3. El Gateway tiene listeners pero no tiene la dirección esperada

Esto aparece con frecuencia en clústeres locales o entornos sin una implementación de LoadBalancer. No es que Gateway API esté roto — simplemente la infraestructura subyacente no está aprovisionando una dirección externa.

Opciones:

  • Verificar si el clúster tiene capacidad LoadBalancer
  • Usar port-forward para validar el camino de enrutamiento

4. El YAML surtió efecto, pero las solicitudes devuelven 404 / 503

En este punto normalmente no es un solo campo incorrecto — es una cadena rota en algún punto:

  • Header Host incorrecto
  • El path no coincide con ninguna regla
  • El Pod de backend no está saludable
  • El selector del Service no está seleccionando ningún Pod

Los problemas de ingreso a veces parecen un fallo del proxy, pero el backend simplemente no estaba listo. No culpes de todo a la capa de proxy — ya tiene suficiente trabajo.

Resumen en una línea

La forma más efectiva de depurar Gateway API no es cambiar el YAML constantemente — es aprender a leer status. Accepted te dice si se recogió la orden. ResolvedRefs te dice si las referencias se resolvieron. Programmed te dice si la configuración fue efectivamente aplicada. Examina esas tres capas por separado y la velocidad de resolución de problemas aumenta drásticamente.

Siguiente paso

Esto completa la serie de 10 artículos sobre Envoy Gateway. Si quieres repasar el mapa completo de la serie:

👉 Resumen de la serie