Cómo solucionar Kubernetes CrashLoopBackOff [Guía completa 2026]

¿Tu Pod está atrapado en estado “CrashLoopBackOff” en Kubernetes, reiniciándose sin fin y sin recuperarse? Este artículo analiza en profundidad las causas detrás de este error de estado más común de Kubernetes y te guía a través de soluciones concretas con la información más actualizada de 2026. Diseñado tanto para principiantes como para usuarios avanzados, esta guía ofrece instrucciones de resolución de problemas paso a paso.

¿Qué es este error? Síntomas que verás
1. Síntomas específicos
2. Alcance del impacto
Causas de este error
Solución 1: Identificar la causa raíz mediante logs y eventos (Recomendado)
Solución 2: Ajustar la configuración de recursos
Solución 3: Corregir la configuración de Probes (Avanzado)
Cómo prevenir este error
Resumen
Referencias

¿Qué es este error? Síntomas que verás

CrashLoopBackOff es un estado de Kubernetes que indica que un contenedor dentro de un Pod se bloquea inmediatamente después de iniciarse, y Kubernetes sigue intentando reiniciarlo, solo para que vuelva a bloquearse en un bucle infinito. No es un error en sí mismo, sino un nombre de estado que indica que un Pod está atrapado en un ciclo de reinicio.

Síntomas específicos

Al ejecutar el comando kubectl get pods, verás una salida como esta:

NAME                        READY   STATUS             RESTARTS      AGE
my-app-6d8f7b9c4-x2k9p     0/1     CrashLoopBackOff   5 (32s ago)   3m

El STATUS muestra “CrashLoopBackOff” y el conteo de RESTARTS sigue aumentando. Kubernetes aumenta exponencialmente el retardo de espera (backoff delay) entre cada reinicio. Comienza en 10 segundos, luego 20 segundos, 40 segundos, y así sucesivamente, con un máximo de 5 minutos.

Alcance del impacto

Cuando ocurre este error, el Pod afectado no puede servir tráfico correctamente. En arquitecturas de microservicios, esto puede propagarse e impactar a todos los servicios dependientes. A partir de 2026, Kubernetes posee aproximadamente el 92% del mercado de orquestación de contenedores, y cada vez más desarrolladores y operadores encuentran este error en entornos de producción.

Causas de este error

CrashLoopBackOff puede tener múltiples causas. A continuación, se explican detalladamente las causas principales.

Causa 1: Errores y bugs de la aplicación

La causa más común son errores en la propia aplicación que se ejecuta dentro del contenedor:

Excepciones no controladas: Una excepción no capturada ocurre durante el inicio de la aplicación, provocando la terminación del proceso
Archivos de configuración faltantes o inválidos: Los archivos de configuración requeridos no se encuentran o tienen un formato incorrecto
Variables de entorno no configuradas o mal configuradas: Variables de entorno necesarias (cadenas de conexión a base de datos, claves API, etc.) no están definidas o están mal configuradas
Fallo en la conexión con servicios dependientes: La aplicación no puede conectarse a una base de datos o API externa al inicio y termina inmediatamente sin reintentar

Causa 2: Recursos insuficientes (OOMKilled)

Cuando la memoria o CPU asignada a un contenedor es insuficiente, el OOM Killer (eliminador por falta de memoria) fuerza la terminación del proceso. Al verificar con kubectl describe pod, la razón de terminación aparece como “OOMKilled” con Exit Code “137” (128 + señal SIGKILL 9).

En Kubernetes, los recursos se controlan mediante resources.requests y resources.limits. Cuando el uso real de memoria de una aplicación supera el límite, se elimina inmediatamente. Lenguajes con recolección de basura como Java y Node.js son particularmente propensos a este problema debido a una mala configuración del tamaño del heap.

Causa 3: Liveness Probe mal configurado

El Liveness Probe de Kubernetes verifica periódicamente si un contenedor está funcionando normalmente. Cuando este probe está mal configurado, el contenedor puede ser reiniciado aunque la aplicación esté realmente sana.

Errores de configuración comunes:
– initialDelaySeconds demasiado corto, provocando que las verificaciones de salud comiencen antes de que la aplicación termine de iniciar
– timeoutSeconds demasiado corto, causando tiempos de espera bajo carga temporal
– El endpoint de verificación de salud no está implementado o apunta a una ruta incorrecta

Causa 4: Problemas con la imagen del contenedor

Etiquetas de imagen inválidas: Especificar una etiqueta inexistente (ej.: latest apuntando a una versión inesperada)
Punto de entrada mal configurado: Errores en el ENTRYPOINT o CMD del Dockerfile
Binarios o bibliotecas faltantes: Las bibliotecas de dependencias requeridas no están incluidas en la imagen del contenedor

Causa 5: Problemas de montaje de volúmenes y permisos

Fallo en el montaje de PersistentVolume: El volumen especificado no está disponible
Permisos de archivo insuficientes: El proceso dentro del contenedor carece de permisos de lectura/escritura para los archivos requeridos
Errores de referencia a ConfigMap/Secret: Referencia a ConfigMaps o Secrets inexistentes

Solución 1: Identificar la causa raíz mediante logs y eventos (Recomendado)

El primer paso más importante para resolver CrashLoopBackOff es identificar la causa raíz a través de logs e información de eventos.

Paso 1: Verificar el estado del Pod y los eventos

Primero, obtén información detallada sobre el Pod problemático:

kubectl describe pod <pod-name> -n <namespace>

Secciones clave en las que enfocarse:

State: El estado actual del contenedor (Waiting, Running, Terminated)
Last State: El estado de terminación anterior y el Exit Code
Events: Historial de eventos recientes (programación, descarga de imagen, inicio, terminación, etc.)

State:          Waiting
  Reason:       CrashLoopBackOff
Last State:     Terminated
  Reason:       Error
  Exit Code:    1
  Started:      Fri, 13 Feb 2026 10:00:00 +0900
  Finished:     Fri, 13 Feb 2026 10:00:05 +0900

Cómo leer los Exit Codes:

Exit Code	Significado
0	Salida normal (puede ser causado por restartPolicy)
1	Error de aplicación
137	OOMKilled (terminación forzada por falta de memoria)
139	Fallo de segmentación
143	SIGTERM (fallo en el apagado graceful)

Paso 2: Verificar los logs del contenedor

Verificar los logs actuales (salida antes del bloqueo):

kubectl logs <pod-name> -n <namespace>

Si el contenedor ya se ha bloqueado, usa la bandera --previous para obtener los logs del bloqueo anterior:

kubectl logs <pod-name> -n <namespace> --previous

Para Pods con múltiples contenedores, especifica el nombre del contenedor:

kubectl logs <pod-name> -c <container-name> -n <namespace> --previous

Paso 3: Verificar eventos en todo el Namespace

Verifica los eventos en todo el Namespace para identificar escasez de recursos o problemas de programación:

kubectl get events -n <namespace> --sort-by='.lastTimestamp'

Notas importantes

Si no se genera ningún log, el contenedor puede estar bloqueándose antes de que se ejecute el punto de entrada. En este caso, sospecha de un problema con la imagen misma.
kubectl logs se reinicia con cada reinicio, lo que hace crucial la opción --previous.
En entornos de producción, usa herramientas de recopilación de logs como Fluentd, Loki o Datadog para almacenar logs de bloqueo de forma persistente.

Solución 2: Ajustar la configuración de recursos

Sigue estos pasos cuando los logs confirmen que OOMKilled o la escasez de recursos es la causa raíz.

Verificar y ajustar límites de memoria/CPU

Verifica la configuración de recursos actual:

kubectl get pod <pod-name> -n <namespace> -o jsonpath='{.spec.containers[*].resources}'

Ejemplo de Deployment con límites de recursos correctamente configurados:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  replicas: 2
  selector:
    matchLabels:
      app: my-app
  template:
    spec:
      containers:
      - name: my-app
        image: my-app:latest
        resources:
          requests:
            memory: "256Mi"
            cpu: "250m"
          limits:
            memory: "512Mi"
            cpu: "500m"

Consejos clave de ajuste

requests: La cantidad de recursos garantizada durante la programación del Pod. Configurar según el uso promedio real
limits: El tope máximo de uso. Configurar con margen sobre el uso pico
Establece los limits de memoria en 1.5-2x los requests para estabilidad
Para aplicaciones Java, configura -Xmx (tamaño máximo del heap) al 70-80% del límite de memoria del contenedor

Verificar el uso real de recursos

En entornos con Metrics Server instalado, puedes verificar el uso de recursos en tiempo real:

kubectl top pod <pod-name> -n <namespace>

Usa estos resultados para ajustar requests y limits a valores apropiados.

Solución 3: Corregir la configuración de Probes (Avanzado)

Sigue estos pasos cuando la causa raíz sea un Liveness o Readiness Probe mal configurado.

Verificar la configuración actual de Probes

kubectl get pod <pod-name> -n <namespace> -o jsonpath='{.spec.containers[*].livenessProbe}'

Configuración recomendada de Probes

En las mejores prácticas de Kubernetes 2026, se recomienda usar Startup Probe. El Startup Probe suprime la ejecución del Liveness Probe hasta que la aplicación haya terminado de iniciar.

containers:
- name: my-app
  image: my-app:latest
  ports:
  - containerPort: 8080
  startupProbe:
    httpGet:
      path: /healthz
      port: 8080
    failureThreshold: 30
    periodSeconds: 10
  livenessProbe:
    httpGet:
      path: /healthz
      port: 8080
    initialDelaySeconds: 0
    periodSeconds: 15
    timeoutSeconds: 5
    failureThreshold: 3
  readinessProbe:
    httpGet:
      path: /ready
      port: 8080
    initialDelaySeconds: 5
    periodSeconds: 10
    timeoutSeconds: 3

Lista de verificación de configuración de Probes

Usa Startup Probes: Esencial para aplicaciones de inicio lento (Spring Boot, aplicaciones grandes de Node.js, etc.)
Asegúrate de que failureThreshold × periodSeconds supere el tiempo máximo de inicio de la aplicación
Mantén la ejecución del probe ligera: No incluyas operaciones pesadas como consultas a base de datos
Configura timeoutSeconds a un valor que permita a la app responder incluso bajo alta carga (el valor predeterminado de 1 segundo suele ser muy corto)

Lanzar un Pod de depuración temporal

Si el contenedor se bloquea inmediatamente al iniciar y no puedes revisar los logs, puedes sobrescribir el punto de entrada y lanzar un Pod de depuración:

kubectl run debug-pod --image=my-app:latest --restart=Never --command -- sleep 3600

Luego accede al contenedor y inicia manualmente la aplicación para investigar errores:

kubectl exec -it debug-pod -- /bin/sh

Cómo prevenir este error

Aquí están las mejores prácticas para prevenir proactivamente CrashLoopBackOff.

1. Verificaciones previas al despliegue en pipelines CI/CD

Valida tus manifiestos antes de desplegar:

# Verificación de sintaxis de manifiestos
kubectl apply --dry-run=client -f deployment.yaml

# Validación de esquema con kubeval/kubeconform
kubeconform -strict deployment.yaml

2. Estimación adecuada de recursos

Mide el uso real de recursos en un entorno de staging
Ejecuta pruebas de carga para entender el uso pico de memoria y CPU
Usa Vertical Pod Autoscaler (VPA) para sugerir automáticamente valores de recursos apropiados

3. Implementar apagado graceful

Maneja correctamente las señales SIGTERM en la aplicación para completar las solicitudes en curso antes de terminar. Configura terminationGracePeriodSeconds a un valor que proporcione tiempo suficiente para el proceso de apagado de tu aplicación.

4. Configurar monitoreo y alertas

Implementa herramientas de monitoreo como Prometheus + Grafana, Datadog o New Relic para vigilar estas métricas:

kube_pod_container_status_restarts_total: Conteo de reinicios del contenedor
kube_pod_status_phase: Fase del Pod
container_memory_usage_bytes: Uso de memoria

Construye mecanismos de alerta que se activen cuando los conteos de reinicio superen los umbrales.

5. No uses la etiqueta latest

La etiqueta latest puede causar cambios de versión inesperados. Siempre usa etiquetas de versión específicas (ej.: v1.2.3) o digests de imagen (SHA256).

Resumen

Kubernetes CrashLoopBackOff es un estado que indica que un Pod está atrapado en un ciclo de reinicio — no es un error en sí mismo. Las causas raíz van desde bugs de aplicación, escasez de recursos, mala configuración de probes, problemas de imagen, hasta problemas de permisos.

Pasos clave para la resolución:
1. Usa kubectl describe pod y kubectl logs --previous para identificar la causa
2. Determina la categoría de la causa a partir del Exit Code y la información de eventos
3. Aplica la corrección apropiada basándote en la causa identificada

Consejos de prevención:
– Usa Startup Probes y configura los Liveness Probes apropiadamente
– Configura requests/limits de recursos basándote en mediciones reales
– Valida los manifiestos en tu pipeline CI/CD antes del despliegue
– Configura monitoreo y alertas para detectar problemas tempranamente

Si los pasos anteriores no resuelven tu problema, considera publicar una pregunta en los foros de la comunidad oficial de Kubernetes (discuss.kubernetes.io) o consultar el soporte de tu proveedor de nube (GKE, EKS, AKS) para problemas específicos del proveedor.