Cuando algo falla en el clúster
Cuando un Pod no funciona, Kubernetes casi siempre te dice por qué. Hay que saber dónde mirar y qué significa cada mensaje.
La idea: Kubernetes deja pistas
Has aplicado tu Deployment, esperas un rato y la aplicación no responde. Lo primero que hay que saber es que Kubernetes no falla en silencio. Cada Pod tiene un estado, cada contenedor tiene un motivo cuando no arranca, y el clúster apunta en un registro de eventos todo lo que ha intentado hacer.
Es como el seguimiento de un paquete de mensajería. Si no te llega, no adivinas: miras el seguimiento. «En almacén», «En reparto», «Dirección incorrecta», «Ausente». Cada estado te dice dónde se ha quedado y qué hacer.
En Kubernetes, el seguimiento es el estado del Pod y sus eventos.
La vida de un Pod: sus fases
Cada Pod está siempre en una de estas cinco fases (phase). Son pocas y conviene sabérselas de memoria:
- Pending
- El Pod está aceptado pero todavía no funciona: espera a que le encuentren nodo o a que se descargue su imagen.
- Running
- El Pod ya tiene nodo y al menos uno de sus contenedores está en marcha.
- Succeeded
- Todos los contenedores del Pod han terminado su trabajo sin errores y no se van a reiniciar. Es lo normal en una tarea que acaba, como un Job.
- Failed
- Todos los contenedores han terminado y al menos uno lo ha hecho con error.
- Unknown
- Kubernetes no sabe en qué estado está el Pod, casi siempre porque ha perdido el contacto con su nodo.
| Fase | Qué significa |
|---|---|
| Pending | El Pod existe, pero aún no tiene todos sus contenedores en marcha. O no tiene nodo asignado todavía, o está descargando la imagen. |
| Running | Está en un nodo y al menos un contenedor está funcionando (o arrancando, o reiniciándose). |
| Succeeded | Todos los contenedores han terminado bien y no se van a reiniciar. |
| Failed | Todos los contenedores han terminado y al menos uno lo hizo con error. |
| Unknown | No se puede saber el estado, casi siempre porque se ha perdido la comunicación con el nodo. |
CrashLoopBackOff, ImagePullBackOff u OOMKilled no son fases. Son motivos que explican el estado de un contenedor. Un Pod en CrashLoopBackOff suele estar en fase Running, porque Kubernetes sigue intentándolo. Las fases son sólo las cinco de arriba.
Y dentro del Pod, el estado de cada contenedor
Además de la fase del Pod, cada contenedor tiene uno de tres estados: Waiting (esperando a arrancar), Running (en marcha) o Terminated (terminado). Cuando está en Waiting o Terminated, lleva un motivo (reason). Ahí es donde aparecen los nombres de error que vas a ver a continuación.
Los errores típicos, uno a uno
- scheduler
- La pieza que decide en qué nodo se coloca cada Pod. Si no encuentra sitio, el Pod se queda en Pending.
- kubelet + runtime
- El encargado del nodo y el programa que arranca los contenedores. Entre los dos descargan la imagen y la ponen en marcha.
- ErrImagePull · ImagePullBackOff
- No se ha podido descargar la imagen: el nombre o la versión están mal, no existe o el registro pide permiso. BackOff significa que Kubernetes reintenta cada vez más espaciado.
- CreateContainerConfigError
- La imagen está, pero falta algo de su configuración para arrancar, como un ConfigMap o un Secret que no existe.
- ConfigMap
- El objeto donde se guarda la configuración de una aplicación fuera de su imagen (lección 03).
- CrashLoopBackOff
- El contenedor arranca, se cae, se reinicia y se vuelve a caer, una y otra vez. Kubernetes espera cada vez más entre intento e intento.
- OOMKilled
- El contenedor ha gastado más memoria de su límite y el sistema lo ha matado. OOM significa «sin memoria».
- NotReady
- El nodo no está sano o no responde, así que no puede ejecutar Pods con normalidad.
Pending que no avanza: no hay sitio
Si un Pod lleva mucho rato en Pending sin nodo asignado, el scheduler no encuentra ningún nodo donde colocarlo. Las causas más habituales:
- Pide más recursos de los que quedan: sus requests de CPU o memoria no caben en ningún nodo (lección 05).
- Taints que no tolera: todos los nodos tienen una «marca» que repele al Pod y el Pod no tiene permiso para ignorarla (lo verás en la lección 06).
- Un disco que no se puede conseguir: el Pod pide un volumen persistente que no está disponible (lección 09).
El evento típico que verás es FailedScheduling, con una frase como «0/3 nodes are available: 3 Insufficient cpu».
ErrImagePull e ImagePullBackOff: no encuentra la imagen
El nodo intenta descargar la imagen y no puede. Primero sale ErrImagePull (el fallo en sí) y, tras varios intentos, ImagePullBackOff (Kubernetes espera cada vez más entre intento e intento). Las causas casi siempre son tres:
- El nombre o la etiqueta de la imagen están mal escritos (ngnix:1.27 en vez de nginx:1.27).
- La imagen está en un registro privado y falta la contraseña para entrar (imagePullSecrets).
- El nodo no tiene salida a internet o al registro.
La palabra BackOff significa siempre lo mismo: «lo he intentado, ha fallado, espero un poco y vuelvo a probar, cada vez esperando más». Kubernetes alarga la espera entre intentos hasta un máximo de 5 minutos.
CrashLoopBackOff: arranca y se cae, una y otra vez
La imagen se descarga bien y el contenedor arranca, pero se cierra enseguida. Kubernetes lo reinicia, vuelve a caerse, lo reinicia… y entre intento e intento espera cada vez más. Ese bucle es CrashLoopBackOff.
El problema está dentro de la aplicación: un error en el código, una variable de configuración que falta, una base de datos a la que no consigue conectar. La pista está en los logs del contenedor, sobre todo en los del intento anterior.
Es como un coche que arranca y se cala nada más soltar el embrague. El motor de arranque funciona (Kubernetes arranca el contenedor), pero algo dentro hace que se pare. Volver a girar la llave no lo arregla: hay que mirar qué pasa dentro.
OOMKilled: se ha pasado de memoria
Lo viste en la lección 05: si un contenedor intenta usar más memoria que su límite, el sistema lo mata. Su estado queda como Terminated con motivo OOMKilled (Out Of Memory, sin memoria). Si pasa una y otra vez, acabarás viendo también CrashLoopBackOff. La solución es dar más memoria al límite o arreglar la aplicación para que gaste menos.
CreateContainerConfigError: falta una pieza de la configuración
La imagen está, pero Kubernetes no puede preparar el contenedor porque falta algo que el Pod necesita: casi siempre un ConfigMap o un Secret que no existe o tiene otro nombre. El mensaje lo dice claramente, por ejemplo: «secret "db-password" not found».
Un nodo en NotReady
A veces el problema no es el Pod sino la máquina. Si el kubelet de un nodo deja de informar al API server, el nodo pasa a NotReady. Puede ser que se haya apagado, que se haya quedado sin red, que el disco esté lleno o que el propio kubelet se haya parado. Pasado un tiempo, Kubernetes saca los Pods de ese nodo y, si los gestiona un controlador, los recrea en otros nodos.
Reiniciar o no: la restartPolicy
Cada Pod dice qué hacer cuando un contenedor termina, con el campo restartPolicy:
| Valor | Qué hace | Uso típico |
|---|---|---|
| Always | Lo reinicia siempre, termine bien o mal. Es el valor por defecto. | Aplicaciones que deben estar siempre en marcha (Deployments). |
| OnFailure | Sólo lo reinicia si terminó con error. | Jobs: tareas que se reintentan si fallan. |
| Never | No lo reinicia nunca. | Tareas de una sola vez en las que quieres ver el fallo tal cual. |
Ojo: el reinicio lo hace el kubelet en el mismo nodo y es el mismo Pod. Sustituir un Pod que ha desaparecido por otro nuevo es trabajo del controlador (ReplicaSet, Job…), que vimos en la lección 03.
Las sondas: Kubernetes pregunta «¿estás bien?»
Que un contenedor esté en marcha no quiere decir que funcione. Una aplicación puede estar colgada y seguir «viva» para el sistema operativo. Por eso Kubernetes permite configurar sondas (probes): comprobaciones periódicas que hace el kubelet, como llamar a una dirección web de la aplicación o ejecutar un comando dentro.
Piensa en el personal de una tienda:
- Startup: «¿Ya has llegado y te has puesto el uniforme?». Hasta que no está listo para empezar, no se le pregunta nada más.
- Readiness: «¿Puedes atender clientes ahora?». Si está ocupado reponiendo, no se le mandan clientes, pero sigue en la tienda.
- Liveness: «¿Sigues respondiendo?». Si se ha quedado bloqueado y no reacciona, se le releva por otro.
- startupProbe
- Sonda de arranque. Pregunta si la aplicación ha terminado de arrancar. Mientras no dice que sí, las otras dos sondas no actúan; si se agota el tiempo, reinicia el contenedor.
- readinessProbe
- Sonda de «listo». Pregunta si la aplicación puede atender ahora. Si falla, se la aparta del tráfico, pero no se la reinicia.
- livenessProbe
- Sonda de «vivo». Pregunta si la aplicación sigue funcionando. Si falla varias veces seguidas, el kubelet reinicia el contenedor.
- Service
- La dirección fija que reparte el tráfico entre los Pods de una aplicación (lección 07). Sólo manda tráfico a los Pods que están listos.
- kubelet
- El encargado de cada nodo. Es quien ejecuta las sondas y reinicia el contenedor cuando toca.
Una tienda online tarda 40 segundos en arrancar porque carga el catálogo. Sin sondas, Kubernetes le mandaría clientes desde el segundo 1 y verían errores. Con una readinessProbe que pregunta a /listo, el Pod no recibe tráfico hasta que el catálogo está cargado.
Si un día la aplicación se bloquea y deja de responder, la livenessProbe que pregunta a /vivo falla, y el kubelet la reinicia sin que nadie tenga que intervenir.
# Dentro de la definición del contenedor readinessProbe: httpGet: path: /listo # dirección que debe responder bien port: 8080 periodSeconds: 5 # pregunta cada 5 segundos livenessProbe: httpGet: path: /vivo port: 8080 failureThreshold: 3 # 3 fallos seguidos = reiniciar
Pregunta muy típica: «el contenedor funciona pero no debe recibir tráfico mientras carga datos». La respuesta es readiness, no liveness. Si eliges liveness, Kubernetes reiniciaría la aplicación en plena carga y nunca terminaría de arrancar.
Y para aplicaciones que tardan mucho en arrancar, la sonda adecuada es startup: protege al contenedor de la liveness hasta que ha terminado de arrancar.
Las herramientas: cuatro comandos
Para investigar un fallo en el clúster casi siempre basta con cuatro comandos de kubectl. En la lección 12 verás herramientas para entrar dentro de la aplicación; aquí nos quedamos en lo que el clúster te cuenta.
| Comando | Para qué sirve |
|---|---|
| kubectl get pods | La foto general: estado, cuántos contenedores están listos y cuántas veces se han reiniciado. |
| kubectl describe pod <nombre> | La ficha completa del Pod, con los motivos de cada contenedor y, al final, sus eventos. Es el comando más útil. |
| kubectl get events | El registro de todo lo que ha pasado en el namespace: Pods programados, imágenes descargadas, fallos… |
| kubectl logs <nombre> | Lo que la aplicación ha escrito por pantalla. Imprescindible en CrashLoopBackOff. |
$ kubectl get pods
NAME READY STATUS RESTARTS AGE
tienda-7d9f8c6b5-2xkqp 1/1 Running 0 3h
tienda-7d9f8c6b5-9hjzt 0/1 CrashLoopBackOff 6 (2m ago) 12m
pedidos-5b4c7f9d8-mn4lw 0/1 ImagePullBackOff 0 5m
informes-6c8d9e7f-qq2rt 0/1 Pending 0 20m
Con sólo esa tabla ya sabes muchas cosas: el segundo Pod se cae al arrancar (mira sus logs), el tercero no encuentra la imagen (revisa el nombre) y el cuarto no tiene sitio (mira sus eventos con describe).
Fíjate en la columna RESTARTS. Un número que no para de crecer es la señal de que algo dentro del contenedor está fallando, aunque el estado diga Running.
Método: qué mirar primero
Ante un Pod que falla, sigue siempre el mismo orden. De lo general a lo concreto:
- get pods
- Lista los Pods con su estado y el motivo si algo va mal. Es lo primero que se mira.
- describe pod
- Enseña la ficha completa de un Pod y, al final, sus eventos: el historial de lo que le ha pasado, con los errores.
- logs
- Muestra los mensajes que escribe la propia aplicación. Ahí aparecen los errores del programa.
- get nodes
- Lista los nodos del clúster y dice si están sanos (Ready) o no.
- Ready
- Estado de un nodo sano y preparado para ejecutar Pods.
| Lo que ves | Primer comando | Qué buscas |
|---|---|---|
| Pending durante mucho rato | kubectl describe pod | Evento FailedScheduling: falta CPU, memoria, un disco o hay taints. |
| ErrImagePull / ImagePullBackOff | kubectl describe pod | Nombre o etiqueta de imagen mal escritos, o falta acceso al registro. |
| CrashLoopBackOff | kubectl logs --previous | El error que escribió la aplicación antes de caerse. |
| OOMKilled | kubectl describe pod | El límite de memoria y el motivo del último cierre. |
| CreateContainerConfigError | kubectl describe pod | El ConfigMap o Secret que falta. |
| Running pero 0/1 READY | kubectl describe pod | La readinessProbe está fallando. |
| Muchos Pods mal en la misma máquina | kubectl get nodes | Un nodo en NotReady. |
Resumen en cinco frases
- Un Pod siempre está en una de cinco fases: Pending, Running, Succeeded, Failed o Unknown.
- Los nombres de error como CrashLoopBackOff, ImagePullBackOff u OOMKilled son motivos del estado de un contenedor, no fases.
- Pending que no avanza es falta de sitio; ImagePullBackOff es la imagen; CrashLoopBackOff es la aplicación; OOMKilled es la memoria.
- La readinessProbe aparta un contenedor del tráfico; la livenessProbe lo reinicia; la startupProbe protege los arranques lentos.
- El orden para investigar es get pods, describe, logs y, si hace falta, get nodes.
Términos del examen
- Pod phase
- La fase de un Pod: Pending, Running, Succeeded, Failed o Unknown.
- Waiting · Running · Terminated
- Los tres estados posibles de un contenedor dentro del Pod.
- FailedScheduling
- Evento que indica que el scheduler no encuentra nodo para el Pod.
- ErrImagePull
- Fallo al descargar la imagen.
- ImagePullBackOff
- Tras varios fallos de descarga, Kubernetes espera cada vez más entre intentos.
- CrashLoopBackOff
- El contenedor arranca, se cae y se reinicia en bucle, con esperas crecientes.
- OOMKilled
- Contenedor terminado por superar su límite de memoria.
- CreateContainerConfigError
- No se puede preparar el contenedor porque falta configuración, como un ConfigMap o un Secret.
- NotReady
- Estado de un nodo que ha dejado de informar o no puede ejecutar Pods.
- restartPolicy
- Qué hacer cuando un contenedor termina: Always, OnFailure o Never.
- Liveness probe
- Comprueba si el contenedor sigue vivo. Si falla, se reinicia.
- Readiness probe
- Comprueba si puede atender. Si falla, deja de recibir tráfico, sin reiniciarse.
- Startup probe
- Comprueba si ya ha arrancado. Hasta entonces, las otras sondas esperan.
- Events
- Registro de lo que el clúster ha hecho o intentado hacer con cada objeto.
- kubectl describe
- Muestra la ficha completa de un objeto, con sus eventos al final.
Comprueba que lo has entendido
1. Which of the following is NOT a valid Pod phase?
- Pending
- Succeeded
- CrashLoopBackOff
- Unknown
Ver respuesta
C. CrashLoopBackOff es el motivo del estado de un contenedor, no una fase. Las fases son sólo cinco: Pending, Running, Succeeded, Failed y Unknown.
2. A Pod has been in Pending state for a long time and its events show "0/3 nodes are available: 3 Insufficient memory". What is the most likely cause?
- The container image does not exist
- The Pod requests more memory than any node has available
- The application crashes at startup
- The liveness probe is failing
Ver respuesta
B. El scheduler no encuentra un nodo con memoria suficiente para los requests del Pod. Si fuera la imagen, el error sería ImagePullBackOff; si fuera la aplicación, CrashLoopBackOff.
3. What happens when a container's readiness probe fails?
- The container is restarted
- The Pod is deleted and recreated on another node
- The Pod is removed from the Service endpoints and stops receiving traffic
- The node is marked NotReady
Ver respuesta
C. La readiness sólo aparta el Pod del tráfico; no lo reinicia. Reiniciar es lo que hace la liveness cuando falla.
4. A Pod shows the status CrashLoopBackOff. Which command is most useful to find out why the application is failing?
- kubectl get nodes
- kubectl logs <pod> --previous
- kubectl scale deployment --replicas=0
- kubectl get namespaces
Ver respuesta
B. En CrashLoopBackOff el problema está dentro de la aplicación, y la pista está en sus logs. Con --previous ves los del intento que se cayó, no los del que acaba de arrancar.
5. Which restartPolicy is the default for Pods?
- Never
- OnFailure
- Always
- OnSuccess
Ver respuesta
C. Por defecto es Always: el contenedor se reinicia siempre que termina. OnSuccess no existe. Los Jobs usan OnFailure o Never.