Una malla mal configurada a menudo no falla de forma ruidosa: el tráfico simplemente no se enruta como esperabas, o un Pod nunca recibe un sidecar que dabas por hecho. istioctl tiene comandos dedicados exactamente para esto: detectar problemas antes de que causen síntomas confusos. Esta guía cubre los que vale la pena ejecutar de forma rutinaria.

istioctl analyze: encuentra problemas de configuración antes de que te afecten

istioctl analyze
istioctl analyze -n my-namespace
istioctl analyze -A

analyze inspecciona la configuración real de Istio de tu clúster, no solo un archivo que estás a punto de aplicar, e informa de problemas reales: un namespace que no está etiquetado para inyección cuando claramente pretendías que lo estuviera, un VirtualService que hace referencia a un host que no existe, configuración en conflicto entre dos recursos. Ejecútalo sin flag de namespace para el namespace predeterminado del contexto actual, con -n para uno específico, o con -A en todos los namespaces del clúster. Hazlo un hábito después de cualquier cambio de configuración, no solo cuando algo esté visiblemente roto; con regularidad detecta un problema antes de que se convierta en un síntoma.

istioctl validate: comprueba un archivo antes de aplicarlo

istioctl validate -f my-virtualservice.yaml

Mientras que analyze inspecciona lo que ya está en vivo en el clúster, validate comprueba un manifiesto antes de aplicarlo, detectando errores de esquema y valores de campo no válidos. Ejecútalo como cosa normal antes de kubectl apply en cualquier cosa relacionada con Istio, el mismo reflejo que ejecutar kubectl apply --dry-run para recursos planos de Kubernetes.

istioctl proxy-status: ¿está cada sidecar sincronizado?

istioctl proxy-status

Esto lista cada sidecar que istiod conoce y si cada uno tiene la configuración más reciente (SYNCED) o va retrasado (STALE, o mostrando un error). Un sidecar atascado en STALE suele ser la explicación real cuando un cambio de enrutamiento que acabas de aplicar no parece surtir efecto en un Pod concreto, algo que conviene comprobar antes de asumir que la configuración en sí es incorrecta.

istioctl proxy-config: ¿qué está ejecutando realmente este sidecar?

Para investigar directamente la configuración de Envoy de un solo Pod, en lugar de adivinar a partir del comportamiento:

istioctl proxy-config routes <pod-name> -n <namespace>
istioctl proxy-config clusters <pod-name> -n <namespace>
istioctl proxy-config listeners <pod-name> -n <namespace>

Es la misma idea de fondo que cubren las guías de Envoy de esta biblioteca sobre inspeccionar una configuración en ejecución, solo que a través del propio wrapper de Istio en lugar de directamente con la API de administración en bruto de Envoy.

La etiqueta app: fácil de pasar por alto, rompe la visualización en silencio

Hay un problema concreto lo bastante común como para destacarlo aparte. Istio (y las herramientas construidas sobre él, como Kiali, que se cubre en la siguiente guía) dependen de una etiqueta app en tus Deployments y Services para construir una imagen precisa de qué cargas de trabajo hablan con cuáles:

metadata:
  labels:
    app: reviews

Si la omites, nada se rompe de forma ruidosa: los Pods se siguen desplegando, los sidecars se siguen inyectando, el tráfico sigue fluyendo. Lo que deja de funcionar en silencio es cualquier cosa que dependa de esa etiqueta para identificar una carga de trabajo: el grafo de servicios de Kiali no renderizará correctamente la conexión, y algunas funciones de gestión de tráfico y telemetría que se basan en app se comportan de forma impredecible. Si una malla parece sana por lo demás pero sus herramientas de observabilidad muestran una imagen confusa o incompleta, la falta de etiquetas app en los Deployments y Services subyacentes es una de las primeras cosas que conviene revisar, precisamente porque el modo de fallo no da ningún mensaje de error que apunte a la causa.

Un hábito razonable que construir

Ejecuta istioctl analyze tras cualquier cambio de configuración, istioctl validate antes de aplicar cualquier cosa nueva y istioctl proxy-status siempre que un cambio no parezca surtir efecto en algún lugar concreto. Ninguno de ellos lo detecta todo, la superficie de configuración de Istio es grande, pero juntos detectan los errores que son a la vez comunes y tediosos de depurar solo mirando YAML.