Saltar a contenido

Observabilidad y Troubleshooting en kgateway

Parte 1: Observabilidad (Viendo el tráfico en la oscuridad)

Para entender cómo fluye el tráfico, kgateway se apoya en los tres pilares clásicos de la observabilidad. Como kgateway está basado en Envoy, la telemetría es increíblemente rica.

1. Logs de Acceso (Access Logging) Por defecto, los pods del proxy de kgateway (Envoy) registran cada petición que pasa por ellos.

  • ¿Para qué sirve? Para ver quién entra, qué código HTTP se le devolvió (200, 404, 503) y cuánto tardó la petición.
  • El comando rápido: kubectl logs -n kgateway-system -l gateway.networking.k8s.io/gateway-name=<tu-gateway> -f
  • Tip de Arquitectura: En producción, debes configurar kgateway para que escupa estos logs en formato JSON y enviarlos a un sistema centralizado como Elasticsearch, Loki o Datadog.

2. Métricas (Prometheus) Envoy exporta métricas de nivel 7 (HTTP) y nivel 4 (TCP) de forma nativa.

  • ¿Qué puedes ver? Peticiones por segundo, latencia media (P99, P95), y tasa de errores.
  • Implementación: kgateway expone un endpoint /stats/prometheus. Solo necesitas configurar un ServiceMonitor (si usas Prometheus Operator) para que Prometheus raspe (scrape) estos datos. A partir de ahí, puedes crear dashboards en Grafana.

3. Trazas Distribuidas (Distributed Tracing)

  • ¿Para qué sirve? Si tienes una arquitectura de microservicios, una traza te permite ver exactamente cuánto tiempo pasó la petición en el Gateway antes de saltar al Pod A, y luego al Pod B.
  • Implementación: kgateway soporta la inyección de cabeceras de OpenTelemetry (OTel), Zipkin o Jaeger.

Parte 2: Metodología de Troubleshooting (Resolución de Problemas)

Cuando un usuario te dice "La página mi-app.com da error 404 o 503", no adivines. Sigue este flujo de trabajo estricto de arriba hacia abajo:

Paso 1: Validar la Infraestructura Base (El Controlador) Si el cerebro no funciona, las rutas no se crearán.

# Verifica que el controlador de kgateway esté corriendo sano
kubectl get pods -n kgateway-system
# Revisa los logs del controlador en busca de errores de sintaxis o permisos
kubectl logs -n kgateway-system -l app=kgateway

Paso 2: Validar la Jerarquía de Gateway API (El Modelo de Roles) La Gateway API te dice exactamente dónde está el error a través de la columna STATUS.

A. Revisa el GatewayClass y el Gateway:

kubectl get gatewayclass
kubectl get gateway -A
  • ¿Qué buscar? El estado debe ser Accepted y Programmed. Si el Gateway dice False en Programmed, significa que Envoy no pudo abrir el puerto (quizás el puerto 80 ya está en uso o falta una IP pública).

B. Revisa el HTTPRoute (La Ruta del Desarrollador): Aquí es donde ocurren el 90% de los errores.

kubectl get httproute -A
  • ¿Qué buscar? Revisa que el estado diga Accepted. Si un desarrollador escribe mal el nombre del Gateway padre o intenta enrutar tráfico a un namespace prohibido, el controlador rechazará la ruta.

Para ver el motivo exacto del rechazo:

kubectl describe httproute <nombre-de-la-ruta>

Ve directo a la sección Conditions al final de la salida. Ahí te dirá "ResolvedRefs = False" si el Servicio de destino no existe.

Paso 3: Validar los Pods del Proxy (Data Plane) Si la configuración en Kubernetes está Accepted, pero el tráfico sigue fallando, el problema está en los proxies físicos de Envoy.

# Mira los eventos de los pods de Envoy
kubectl describe pod -n kgateway-system -l gateway.networking.k8s.io/gateway-name=<tu-gateway>

🚀 Errores Clásicos y Cómo Solucionarlos (Modo Producción)

  1. Error 503 Service Unavailable:
  2. Causa: kgateway recibió la petición, leyó el HTTPRoute, y sabe a qué Service enviarla, pero no hay Pods sanos detrás de ese Servicio.

  3. Solución: Revisa que los Pods de tu aplicación estén en Running y que los Endpoints del servicio existan (kubectl get endpoints <nombre-servicio>).

  4. Error 404 Not Found:

  5. Causa: kgateway recibió la petición pero no encontró ningún HTTPRoute que haga match con ese dominio (Host) o con esa ruta (/api, /web).

  6. Solución: Revisa la sección hostnames y matches en tu manifiesto HTTPRoute. ¡Cuidado con los errores tipográficos!

  7. El Gateway se queda en Pending (No hay IP Pública):

  8. Causa: Estás en un entorno bare-metal o local (Multipass) y no hay un proveedor de nube que te asigne un LoadBalancer externo.

  9. Solución: Instalar MetalLB para aprovisionar IPs físicas locales, o cambiar el tipo de servicio del Gateway a NodePort.

  10. Error de Certificado (TLS):

  11. Causa: El certificado en tu Secret expiró o no coincide con el dominio.
  12. Solución: Verifica que el Secret existe en el mismo namespace que el Gateway (o que tienes un ReferenceGrant si está en otro namespace) y revisa los logs del controlador para ver si Envoy rechazó el montaje del certificado.

💡 Tip de Oro del Instructor: Si alguna vez configuras todo perfecto pero el tráfico hace cosas extrañas (ej. va a la versión incorrecta), recuerda que Envoy es altamente dinámico. Puedes hacer un "port-forward" al puerto de administración de Envoy (usualmente el 15000) y ver el estado crudo de los clústeres internos: kubectl port-forward <envoy-pod> 15000:15000 y luego visitar http://localhost:15000/clusters en tu navegador para ver si Envoy realmente "ve" las IPs de tus Pods destino.