Dominando kubectl logs y describe para una depuración eficiente de Pods
La depuración de aplicaciones en un entorno distribuido como Kubernetes puede ser un desafío. Cuando un pod no se inicia, entra en un bucle de reinicio o exhibe un comportamiento inesperado, las dos herramientas más cruciales en la caja de herramientas de un operador de Kubernetes son kubectl describe y kubectl logs.
Estos comandos proporcionan vistas diferentes, pero complementarias, del estado y el historial de un Pod de Kubernetes. kubectl describe ofrece los metadatos, el estado, las variables de entorno del Pod y, lo que es crucial, un historial de eventos del sistema. kubectl logs proporciona las transmisiones de salida estándar (stdout) y error estándar (stderr) generadas por la propia aplicación en contenedores.
Dominar los parámetros (flags) y las técnicas asociadas a estos comandos es esencial para diagnosticar y resolver problemas rápidamente, mejorando significativamente la eficiencia general de la solución de problemas de su clúster.
El flujo de trabajo de depuración de Pods en tres pasos
Antes de sumergirnos en los comandos, es útil comprender el flujo de trabajo de depuración típico:
- Verificar el estado: Use
kubectl get podspara identificar el estado de fallo (Pending,CrashLoopBackOff,ImagePullBackOff, etc.). - Obtener contexto y eventos: Use
kubectl describe podpara comprender por qué ocurrió la transición de estado (por ejemplo, el planificador falló, la sonda de vivacidad falló, el volumen no se pudo montar). - Inspeccionar la salida de la aplicación: Use
kubectl logspara examinar el comportamiento de la aplicación en tiempo de ejecución (por ejemplo, errores de configuración, fallos de conexión a la base de datos, rastros de pila).
1. kubectl describe: La herramienta de triaje del sistema
kubectl describe es el primer comando que debe ejecutar cuando un Pod se comporta mal. No muestra la salida de la aplicación, pero proporciona los metadatos y el historial críticos que el propio Kubernetes ha registrado sobre el Pod.
Uso básico
El uso fundamental solo requiere el nombre del Pod:
kubectl describe pod my-failing-app-xyz789
Secciones clave en la salida
Al revisar la salida de describe, céntrese en estas secciones críticas:
A. Status y State (Estado)
Observe el campo Status en la parte superior y luego revise los estados de los contenedores individuales dentro del Pod. Esto le indica si el contenedor está Running (en ejecución), Waiting (esperando) o Terminated (terminado), y proporciona el motivo de ese estado.
| Campo | Estado/Motivo Común | Significado |
|---|---|---|
Status |
Pending |
El Pod está esperando ser programado o le faltan recursos. |
Reason |
ContainerCreating |
El tiempo de ejecución del contenedor está extrayendo la imagen o ejecutando la configuración. |
State |
Waiting / Reason: CrashLoopBackOff |
El contenedor se inició y salió repetidamente. |
State |
Terminated / Exit Code |
El contenedor finalizó la ejecución. Los códigos de salida distintos de cero generalmente indican errores. |
B. Configuración del contenedor
Esta sección verifica que sus variables de entorno, solicitudes/límites de recursos, montajes de volumen y sondas de vivacidad/disponibilidad (liveness/readiness probes) estén definidos correctamente, coincidiendo con el manifiesto que aplicó.
C. La sección Events (Crucial)
La sección Events (Eventos), ubicada en la parte inferior de la salida, es posiblemente la parte más valiosa. Proporciona un registro cronológico de lo que el plano de control de Kubernetes hizo al Pod y para él, incluidas advertencias y errores.
Errores comunes revelados por Events:
- Problemas de programación (Scheduling Issues):
Warning FailedScheduling: Indica que el planificador no pudo encontrar un nodo adecuado (por ejemplo, debido a restricciones de recursos, taints de nodo o reglas de afinidad). - Fallos en la extracción de imágenes (Image Pull Failures):
Warning Failed: ImagePullBackOff: Indica que el nombre de la imagen es incorrecto, la etiqueta no existe, o Kubernetes carece de credenciales para extraerla de un registro privado. - Errores de volumen (Volume Errors):
Warning FailedAttachVolume: Indica problemas al conectar el almacenamiento externo.
Consejo: Si la sección
Eventsestá limpia, el problema suele estar relacionado con la aplicación (bloqueo en tiempo de ejecución, fallo de inicialización, error de configuración), dirigiéndole a usarkubectl logsa continuación.
2. kubectl logs: Inspeccionando la salida de la aplicación
Si describe muestra que el Pod fue programado exitosamente y los contenedores intentaron ejecutarse, el siguiente paso es verificar las transmisiones de salida estándar usando kubectl logs.
Recuperación básica de registros y transmisión en tiempo real
Para ver los registros actuales del contenedor principal en un Pod:
# Recuperar todos los registros hasta el momento actual
kubectl logs my-failing-app-xyz789
# Transmitir registros en tiempo real (útil para monitorear el inicio)
kubectl logs -f my-failing-app-xyz789
Manejo de Pods multi-contenedor
Para pods que utilizan el patrón Sidecar u otros diseños multi-contenedor, debe especificar los registros de qué contenedor desea ver usando el parámetro -c o --container.
# Ver registros del contenedor 'sidecar-proxy' dentro del Pod
kubectl logs my-multi-container-pod -c sidecar-proxy
# Transmitir registros del contenedor de la aplicación principal
kubectl logs -f my-multi-container-pod -c main-app
Depuración de contenedores que se reinician (--previous)
Uno de los escenarios de depuración más comunes es el estado CrashLoopBackOff. Cuando un contenedor se reinicia, kubectl logs solo muestra la salida del intento actual (fallido), que a menudo solo contiene el mensaje de inicio antes del fallo.
Para ver los registros de la instancia anterior, terminada, que contiene el error real que causó la salida, use el parámetro --previous (-p):
# Ver registros de la instancia del contenedor anterior que falló
kubectl logs my-crashloop-pod --previous
# Combinar con la especificación del contenedor si es necesario
kubectl logs my-crashloop-pod -c worker --previous
Limitación de la salida
Para registros de gran volumen, recuperar todo el historial puede ser lento o abrumador. Use --tail para limitar la salida a las últimas N líneas.
# Mostrar solo las últimas 50 líneas de los registros del contenedor
kubectl logs my-high-traffic-app --tail=50
3. Combinando técnicas para un diagnóstico avanzado
La depuración efectiva a menudo implica cambiar rápidamente entre describe y comandos logs específicos.
Caso de estudio: Diagnóstico de fallo de la sonda de vivacidad (Liveness Probe)
Imagine que un Pod está atascado en Running pero se reinicia ocasionalmente, causando interrupciones.
Paso 1: Verificar describe para la vista del sistema.
kubectl describe pod web-server-dpl-abc
La salida muestra en la sección Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Warning Unhealthy 2s kubelet, node-a01 Liveness probe failed: HTTP GET http://10.42.0.5:8080/health failed: 503 Service Unavailable
Conclusión del Paso 1: El contenedor se está ejecutando, pero la sonda de vivacidad está fallando con un error 503, lo que provoca que Kubernetes reinicie el contenedor.
Paso 2: Verificar logs para el contexto de la aplicación.
Ahora, investigue por qué la aplicación devuelve un estado 503, lo cual es un fallo a nivel de aplicación.
kubectl logs web-server-dpl-abc --tail=200
La salida del registro revela:
2023-10-26 14:01:15 ERROR Database connection failure: Timeout connecting to DB instance 192.168.1.10
Conclusión final: El Pod se está reiniciando debido a un fallo en la sonda de vivacidad, y la sonda está fallando porque la aplicación no puede conectarse a la base de datos. El problema es la configuración de red externa o de la base de datos, no el contenedor en sí.
Buenas prácticas y advertencias
| Práctica | Comando | Fundamento |
|---|---|---|
| Siempre verificar los registros anteriores | kubectl logs --previous |
Necesario para diagnosticar CrashLoopBackOff. El error crítico casi siempre se encuentra en la ejecución anterior. |
| Especificar contenedores | kubectl logs -c <name> |
Evita la ambigüedad en Pods multi-contenedor y previene la obtención de registros de sidecars no deseados. |
| Usar etiquetas para operaciones masivas | kubectl logs -l app=frontend -f |
Permite transmitir registros de múltiples Pods que coinciden con un selector simultáneamente (útil para actualizaciones continuas). |
| Advertencia: Rotación de Registros | N/A | Los nodos de Kubernetes realizan la rotación de registros. Los registros más antiguos que la política de retención configurada del nodo (a menudo unos pocos días o según el tamaño) se purgarán y no estarán disponibles a través de kubectl logs. Utilice una solución de registro centralizada externa (por ejemplo, Fluentd, Loki, Elastic Stack) para la retención a largo plazo. |
Conclusión
kubectl describe y kubectl logs son los comandos centrales indispensables para la depuración en Kubernetes. Al tratar a describe como el informe de estado del sistema (centrándose en la configuración, eventos y errores de programación) y a logs como la transmisión de ejecución de la aplicación (centrándose en errores de código y comportamiento en tiempo de ejecución), puede reducir sistemáticamente la causa de casi cualquier fallo de Pod, reduciendo significativamente el Tiempo Medio de Resolución (MTTR) dentro de su clúster.