KCNA en ruta
Lección 10 · Orquestación de contenedores (28 %)

Cuando algo falla en el clúster

Tema del examen: TroubleshootingLectura: 15 min

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.

Imagínatelo así

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:

Fases de un Pod: Pending, Running y después Succeeded o Failed; Unknown cuando no se sabe nada del nodo Pending esperando Running en marcha Succeeded terminó bien (código 0) Failed terminó con error Unknown no se sabe nada del nodo
Qué es cada cosa
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.
Succeeded y Failed sólo aparecen en Pods que terminan, como los de un Job. Una web normal se queda en Running.
FaseQué significa
PendingEl Pod existe, pero aún no tiene todos sus contenedores en marcha. O no tiene nodo asignado todavía, o está descargando la imagen.
RunningEstá en un nodo y al menos un contenedor está funcionando (o arrancando, o reiniciándose).
SucceededTodos los contenedores han terminado bien y no se van a reiniciar.
FailedTodos los contenedores han terminado y al menos uno lo hizo con error.
UnknownNo se puede saber el estado, casi siempre porque se ha perdido la comunicación con el nodo.
Ojo en el examen

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

En qué paso del camino se atasca cada error: al buscar nodo, al descargar la imagen, al arrancar o mientras funciona 1. Buscar nodoscheduler 2. Bajar imagenkubelet + runtime 3. Arrancarconfiguración 4. Funcionarla aplicación Pendingno cabe enningún nodo ErrImagePullImagePullBackOffno encuentra la imagen CreateContainerConfigErrorfalta un ConfigMap… CrashLoopBackOffOOMKilledse cae al funcionar Por debajo de todo: el nodo si el nodo está NotReady, sus Pods dejan de funcionar aunque estén bien configurados
Qué es cada cosa
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.
Saber en qué paso se ha quedado el Pod ya te dice la mitad de la solución.

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:

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:

Para recordar

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.

Imagínatelo así

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:

ValorQué haceUso típico
AlwaysLo reinicia siempre, termine bien o mal. Es el valor por defecto.Aplicaciones que deben estar siempre en marcha (Deployments).
OnFailureSólo lo reinicia si terminó con error.Jobs: tareas que se reintentan si fallan.
NeverNo 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.

Imagínatelo así

Piensa en el personal de una tienda:

Qué pasa cuando falla cada sonda: startup retrasa las demás, readiness quita el tráfico, liveness reinicia el contenedor startupProbe «¿ya has arrancado?» Mientras no responde: las otras dos sondas esperan Si se agota el tiempo: reinicia readinessProbe «¿puedes atender?» Si falla: deja de recibir tráfico del Service El contenedor NO se reinicia livenessProbe «¿sigues vivo?» Si falla varias veces: el kubelet mata el contenedor y lo reinicia
Qué es cada cosa
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.
La diferencia clave: readiness aparta el contenedor del tráfico; liveness lo reinicia.
Ejemplo

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
Ojo en el examen

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.

ComandoPara qué sirve
kubectl get podsLa 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 eventsEl 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).

Para recordar

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:

Método de diagnóstico: get pods, describe, logs y, si hace falta, revisar el nodo 1. Ver el estado get pods ¿qué estado y motivo? 2. Leer la ficha describe pod ¿qué dicen los eventos? 3. Leer la app logs ¿qué error escribe? 4. El nodo get nodes ¿está Ready? de lo general a lo concreto: casi siempre la respuesta aparece en el paso 2 o en el 3
Qué es cada cosa
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.
Cuatro pasos en orden. No hace falta saber nada más para la mayoría de los fallos.
Lo que vesPrimer comandoQué buscas
Pending durante mucho ratokubectl describe podEvento FailedScheduling: falta CPU, memoria, un disco o hay taints.
ErrImagePull / ImagePullBackOffkubectl describe podNombre o etiqueta de imagen mal escritos, o falta acceso al registro.
CrashLoopBackOffkubectl logs --previousEl error que escribió la aplicación antes de caerse.
OOMKilledkubectl describe podEl límite de memoria y el motivo del último cierre.
CreateContainerConfigErrorkubectl describe podEl ConfigMap o Secret que falta.
Running pero 0/1 READYkubectl describe podLa readinessProbe está fallando.
Muchos Pods mal en la misma máquinakubectl get nodesUn nodo en NotReady.

Resumen en cinco frases

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?

  1. Pending
  2. Succeeded
  3. CrashLoopBackOff
  4. 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?

  1. The container image does not exist
  2. The Pod requests more memory than any node has available
  3. The application crashes at startup
  4. 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?

  1. The container is restarted
  2. The Pod is deleted and recreated on another node
  3. The Pod is removed from the Service endpoints and stops receiving traffic
  4. 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?

  1. kubectl get nodes
  2. kubectl logs <pod> --previous
  3. kubectl scale deployment --replicas=0
  4. 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?

  1. Never
  2. OnFailure
  3. Always
  4. OnSuccess
Ver respuesta

C. Por defecto es Always: el contenedor se reinicia siempre que termina. OnSuccess no existe. Los Jobs usan OnFailure o Never.