Troubleshooting en Kubernetes: comandos, errores clave y cómo resolverlos

TLDR:
El troubleshooting en Kubernetes funciona de abajo hacia arriba: revisa el estado de los pods, inspecciona los eventos, consulta los logs y, si hace falta, depura de forma interactiva. La mayoría de los problemas se reduce a un puñado de errores recurrentes (ImagePullBackOff, CrashLoopBackOff, Pending, OOMKilled), todos rastreables con kubectl describe/logs. Para prevenir problemas recurrentes, define requests y límites de recursos adecuados, ajusta los probes, monitorea de forma continua y aplica right-sizing a tus workloads con el tiempo.

Códigos de error comunes en Kubernetes y sus soluciones

ImagePullBackOff

Problema: ImagePullBackOff ocurre cuando Kubernetes no puede descargar la imagen de contenedor necesaria para iniciar un pod. Después de la primera falla al descargar la imagen, Kubernetes reintenta la operación con demoras cada vez más largas. Hasta que la imagen esté disponible, el pod permanece sin ejecutarse.

Diagnóstico: Las fallas al descargar imágenes suelen deberse a nombres de imagen inválidos, tags incorrectos, credenciales del registry faltantes, tokens de autenticación expirados, caídas del registry o problemas de conectividad de red. El punto de partida más útil es la sección de Eventos de la descripción del pod.

Ejecuta kubectl describe pod <pod-name> y busca mensajes como ErrImagePull, pull access denied, unauthorized o manifest unknown. Estos mensajes suelen indicar si la falla está relacionada con la autenticación, la disponibilidad de la imagen o la conectividad.

Flujo de resolución:

1. Ejecuta kubectl describe pod <pod-name> y revisa la sección de Eventos.
2. Verifica que el nombre y el tag de la imagen sean correctos y existan en el registry.
3. Confirma que el registry de contenedores sea accesible desde los nodos del clúster.
4. Valida los secrets de descarga de imágenes configurados en el pod o en la cuenta de servicio.
5. Revisa las credenciales del registry, los permisos y el estado de expiración de los tokens.
6. Verifica la resolución de DNS y la conectividad de red saliente desde los nodos worker.
7. Revisa las configuraciones de proxy, firewall o políticas de red que puedan bloquear el acceso al registry.

Ejemplo

kubectl describe pod my-pod
kubectl get secrets
kubectl describe secret registry-secret

CrashLoopBackOff

Problema: CrashLoopBackOff indica que un contenedor arranca, termina y es reiniciado por Kubernetes una y otra vez. Después de varias fallas consecutivas, Kubernetes introduce demoras crecientes entre los intentos de reinicio para evitar ciclos constantes de reinicio.

Diagnóstico: Esta condición suele deberse a fallas en el arranque de la aplicación, valores de configuración inválidos, variables de entorno faltantes, fallas al inicializar dependencias, problemas de conectividad con la base de datos o comandos de contenedor incorrectos.

Los logs del contenedor suelen ser la forma más rápida de identificar la causa raíz. Revisa los logs con kubectl logs <pod-name>. Si el contenedor se reinicia demasiado rápido, usa el flag --previous para recuperar los logs de la última instancia fallida. La descripción del pod también puede revelar razones de terminación, códigos de salida, conteos de reinicios y fallas en los probes.

Flujo de resolución:

1. Revisa los logs de la aplicación con kubectl logs <pod-name>.
2. Si es necesario, recupera los logs de la instancia anterior del contenedor con --previous.
3. Inspecciona los eventos del pod y los detalles de terminación con kubectl describe pod <pod-name>.
4. Verifica las variables de entorno, los archivos de configuración, los secrets y los comandos de arranque.
5. Revisa las conexiones a bases de datos, las dependencias externas y los endpoints de servicios.
6. Revisa los límites de CPU y memoria en busca de señales de agotamiento de recursos.
7. Valida la configuración de los probes de readiness, startup y liveness, y ajusta los umbrales de tiempo si es necesario.

Ejemplo

kubectl logs my-pod
kubectl logs my-pod --previous
kubectl describe pod my-pod

Pending

Problema: Un pod entra en el estado Pending cuando Kubernetes acepta la definición del pod pero no puede asignarlo a un nodo adecuado. El workload permanece sin programar y no arranca hasta que se cumplan todos los requisitos de scheduling.

Diagnóstico: Los pods en estado Pending suelen deberse a recursos insuficientes en el clúster, reglas de scheduling restrictivas, fallas en el aprovisionamiento de almacenamiento o restricciones de ubicación en nodos. Los mensajes de scheduling comunes incluyen CPU insuficiente, memoria insuficiente, selectores de nodo sin coincidencias, conflictos de taints o PersistentVolumeClaims sin vincular.

Los eventos de scheduling que muestra kubectl describe pod <pod-name> normalmente identifican la razón exacta por la que el scheduler no pudo ubicar el workload.

Flujo de resolución:

1. Ejecuta kubectl describe pod <pod-name> y revisa los eventos del scheduler.
2. Verifica la disponibilidad de los nodos con kubectl get nodes.
3. Confirma que existan suficientes recursos de CPU y memoria en el clúster.
4. Revisa los selectores de nodo, las reglas de afinidad de nodos, los taints y las tolerations.
5. Valida que estén presentes los labels de nodo requeridos.
6. Revisa los PersistentVolumeClaims (PVC) y el estado del aprovisionamiento de almacenamiento.
7. Si el autoescalado está habilitado, confirma que el cluster autoscaler funcione correctamente.

Ejemplo

kubectl describe pod my-pod
kubectl get nodes
kubectl get pvc

OOMKilled

Problema: OOMKilled ocurre cuando un contenedor supera su límite de memoria configurado y es terminado por el OOM killer de Linux. Kubernetes aplica los límites de memoria de forma estricta, lo que hace que el contenedor se detenga de inmediato al superar el límite.

Diagnóstico: El agotamiento de memoria puede deberse a fugas de memoria, uso excesivo de caché, comportamiento ineficiente de la aplicación, picos de tráfico, conjuntos de datos grandes o límites de memoria demasiado bajos para el workload.

La descripción del pod suele mostrar OOMKilled como razón de terminación. Herramientas de monitoreo de recursos como Prometheus, Grafana o Metrics Server pueden ayudar a determinar si el workload experimenta presión de memoria sostenida o picos repentinos de uso.

Flujo de resolución:

1. Confirma la razón de terminación con kubectl describe pod <pod-name>.
2. Revisa las métricas de consumo de memoria previas a la falla.
3. Identifica picos de memoria, fugas o una utilización alta sostenida.
4. Compara el uso real de memoria con los requests y límites configurados.
5. Aumenta los límites de memoria si claramente son insuficientes.
6. Investiga causas a nivel de aplicación como caché, concurrencia o fugas de memoria.
7. Optimiza el uso de memoria de la aplicación y ajusta la configuración de recursos según el comportamiento observado del workload.

Ejemplo

kubectl describe pod my-pod
kubectl top pod my-pod
kubectl top nodes

5 formas de prevenir problemas en Kubernetes desde el inicio

Los equipos que trabajan bien con Kubernetes planifican sus clústeres de forma que se minimicen las fallas comunes. Esto favorece la resiliencia y, además, facilita el troubleshooting cuando surgen los problemas.

1. Define requests y límites de recursos

Los requests y límites de recursos ayudan a Kubernetes a asignar CPU y memoria de forma predecible en todo el clúster. Los requests definen los recursos mínimos necesarios para el scheduling, mientras que los límites definen el máximo de recursos que un contenedor puede consumir. Una configuración adecuada evita que los workloads compitan agresivamente por los recursos compartidos.

Sin requests, el scheduler no puede tomar decisiones de ubicación precisas, lo que puede llevar a nodos sobrecargados y workloads inestables. Sin límites, un solo contenedor puede consumir memoria o CPU en exceso y afectar a otras aplicaciones que corren en el mismo nodo.

Unos límites configurados con cuidado ayudan a reducir el riesgo de eventos OOMKilled, throttling de CPU y agotamiento de recursos en los nodos. Sin embargo, límites demasiado bajos también pueden generar inestabilidad al restringir las aplicaciones durante los picos de carga.

Usar políticas de LimitRange y ResourceQuota a nivel de namespace ayuda a aplicar prácticas consistentes de gestión de recursos entre equipos y entornos. Estos controles reducen la probabilidad de que workloads mal configurados afecten la estabilidad del clúster.

2. Usa los readiness y liveness probes con cuidado

Los probes de readiness y liveness ayudan a Kubernetes a determinar si los contenedores están saludables y listos para recibir tráfico. Una configuración adecuada de los probes mejora la confiabilidad de las aplicaciones al evitar que pods en mal estado atiendan solicitudes y al reiniciar automáticamente los contenedores que fallan.

Los readiness probes controlan si un pod se agrega a la lista de endpoints de un servicio. Si el readiness probe falla, el tráfico deja de enrutarse al pod hasta que se recupere. Esto ayuda a evitar que los usuarios lleguen a aplicaciones degradadas o inicializadas parcialmente.

Los liveness probes detectan bloqueos de la aplicación o procesos que no responden. Cuando un liveness probe falla repetidamente, Kubernetes reinicia el contenedor de forma automática. Este mecanismo mejora la capacidad de autorreparación, pero también puede generar inestabilidad si se configura mal.

Configurar tiempos demasiado agresivos en los probes es una causa frecuente de reinicios innecesarios y condiciones de CrashLoopBackOff. Las aplicaciones que requieren tiempos de arranque largos pueden no superar las verificaciones de salud antes de completar la inicialización. Los startup probes suelen ser útiles para workloads con procesos de arranque lentos.

3. Monitorea eventos, logs y métricas

El monitoreo continuo es esencial para detectar problemas en Kubernetes antes de que escalen a interrupciones del servicio. Los logs, las métricas y los eventos del clúster brindan visibilidad sobre el comportamiento de los workloads, el uso de recursos, la salud de la infraestructura y las fallas operativas.

Plataformas de métricas como Prometheus y Grafana ayudan a seguir el uso de CPU, el consumo de memoria, los reinicios de pods, la latencia de red y el rendimiento del almacenamiento. Monitorear las tendencias a lo largo del tiempo permite identificar comportamientos anormales antes de que los servicios se vuelvan inestables.

Los sistemas de logging centralizados mejoran el troubleshooting al reunir los logs de contenedores, los logs de nodos y los eventos del sistema en una plataforma con capacidad de búsqueda. Herramientas como Elasticsearch, Fluent Bit, Loki y Splunk se usan comúnmente para recolectar y analizar logs de Kubernetes.

Los eventos de Kubernetes aportan contexto operativo adicional al registrar fallas de scheduling, errores al descargar imágenes, desalojos de pods y problemas de configuración. Como los eventos son temporales, recolectarlos y almacenarlos externamente mejora la capacidad de troubleshooting a largo plazo.

4. Usa namespaces y labels de forma consistente

Los namespaces ayudan a organizar los workloads y aislar los recursos dentro de un clúster de Kubernetes. Un uso consistente de los namespaces mejora la claridad operativa, el control de acceso, la gestión de recursos y la eficiencia del troubleshooting.

Separar entornos como desarrollo, staging y producción en namespaces distintos reduce el riesgo de interferencias accidentales entre workloads. Las políticas a nivel de namespace también pueden aplicar límites de seguridad y cuotas de recursos.

Los labels aportan metadatos que se usan para seleccionar, agrupar, monitorear y automatizar workloads. Los servicios, deployments, políticas de red y sistemas de monitoreo de Kubernetes dependen en gran medida de los labels para identificar los workloads.

Los esquemas de etiquetado inconsistentes o mal diseñados suelen causar fallas en el enrutamiento de servicios, confusión en los deployments y complejidad operativa. Los labels estandarizados facilitan buscar, monitorear y gestionar workloads en clústeres grandes.

5. Aplica right-sizing continuo a tus workloads según el uso real

Los requerimientos de recursos de los workloads cambian con el tiempo a medida que las aplicaciones evolucionan, los patrones de tráfico se modifican y crece el uso de la infraestructura. Aplicar right-sizing continuo a los workloads ayuda a mantener el rendimiento y, al mismo tiempo, a reducir la pérdida de recursos en el clúster.

Los workloads sobreaprovisionados malgastan CPU y memoria, lo que aumenta los costos de infraestructura y reduce la eficiencia del clúster. Los workloads subaprovisionados generan inestabilidad, fallas de scheduling, throttling de CPU y caídas relacionadas con la memoria.

Monitorear el comportamiento real de los workloads brinda los datos necesarios para optimizar los requests y límites de recursos. Conviene revisar los patrones de uso a largo plazo en lugar de basarse solo en picos de corto plazo o en las estimaciones del deployment inicial.

Herramientas como el Vertical Pod Autoscaler (VPA) pueden recomendar o ajustar automáticamente la configuración de recursos según el consumo observado. El Horizontal Pod Autoscaler (HPA) complementa este enfoque al escalar el número de réplicas en respuesta a los cambios de carga.

Cómo PerfectScale te ayuda a prevenir y resolver problemas en Kubernetes

La mayor parte del troubleshooting en Kubernetes es reactivo: esperas a que un pod falle y luego escarbas entre eventos, logs y métricas para encontrar la causa. PerfectScale invierte ese modelo al aplicar right-sizing autónomo a los workloads, evitar tiempos de inactividad y optimizar el uso de recursos para mantener una disponibilidad del 99.99%. En lugar de perseguir manualmente eventos de OOMKilled, CrashLoopBackOff y throttling, tus equipos de DevOps, SRE e ingeniería de plataforma obtienen una remediación continua y basada en datos en cada capa del stack de K8s.

Capacidades clave de PerfectScale:

• Remediación automática de problemas: Identifica y corrige al instante los riesgos de resiliencia para maximizar el tiempo de actividad y eliminar la latencia, abordando problemas como OOM, throttling de CPU y desalojos de pods antes de que deriven en interrupciones en cascada.
• Prevención de errores de configuración: Detecta las configuraciones incorrectas detrás de las fallas comunes, como requests de CPU faltantes, requests de memoria faltantes y límites de memoria sin definir, para que los workloads arranquen y funcionen de forma confiable.
• Detección de subaprovisionamiento: Pone en evidencia CPU y memoria subaprovisionadas (tanto requests como límites) y posibles fugas de memoria: las causas raíz que mantienen a los pods atascados en ciclos de reinicio incluso cuando los nodos parecen saludables.
• Fortalecimiento de la infraestructura: Obtén visibilidad integral de los nodos para evitar su sobreasignación, validar afinidades de nodos y taints, y elegir los tipos de nodo óptimos para tus workloads.
• Priorización basada en impacto: Alinea las alertas con tus SLA y SLO, recibe notificaciones instantáneas por Slack, MS Teams o Datadog, y escala los problemas a un ticket con un solo clic.
• Optimización del autoescalado: Ajusta con precisión las configuraciones de autoescalado horizontal y vertical para que los disparadores de escalado se activen correctamente, evitando los escenarios de "HPA al máximo de réplicas" y de agotamiento de recursos que generan inestabilidad.

FAQ

¿Cuál es el primer comando que debo ejecutar cuando un pod tiene problemas? kubectl get pods para identificar el pod con fallas, y luego kubectl describe pod <pod-name> para ver los detalles de su estado y los eventos recientes.

¿Qué causa CrashLoopBackOff? El contenedor arranca, termina y se reinicia una y otra vez — generalmente por una falla en el arranque, una configuración incorrecta, variables de entorno faltantes o un error de conexión a la base de datos o a una dependencia. Revisa primero kubectl logs <pod-name> --previous.

¿Qué causa ImagePullBackOff? Kubernetes no puede descargar la imagen del contenedor — a menudo por un nombre o tag de imagen inválido, credenciales del registry faltantes o expiradas, o un problema de red para llegar al registry.

¿Por qué mi pod está atascado en Pending? El scheduler no puede ubicarlo — típicamente por CPU/memoria insuficientes en el clúster, selectores de nodo o taints sin coincidencias, o un PersistentVolumeClaim sin vincular. kubectl describe pod <pod-name> muestra la razón exacta del scheduling.

¿Qué significa OOMKilled? El contenedor superó su límite de memoria y fue terminado por el OOM killer de Linux. Compara el uso de memoria con los requests/límites configurados y busca fugas o límites insuficientes.

¿Cómo depuro problemas de red o DNS? Usa kubectl get endpoints para confirmar que los pods estén asociados a un servicio, y kubectl exec -it <pod-name> -- nslookup <service-name> para probar la resolución de DNS desde dentro de un pod.

¿Cómo puedo prevenir estos problemas en lugar de solo reaccionar? Define requests/límites de recursos adecuados, configura los probes de readiness/liveness con cuidado, monitorea logs/eventos/métricas de forma continua, usa namespaces y labels consistentes, y aplica right-sizing a los workloads con el tiempo (por ejemplo, con VPA/HPA o una herramienta como PerfectScale).

¿Listo para dejar de apagar incendios en Kubernetes? Explora la plataforma de rendimiento y resiliencia para Kubernetes de PerfectScale y descubre cómo la optimización autónoma mantiene tus clústeres estables, resilientes y rentables.