# Cómo diagnosticar errores y reinicios de pods en Kubernetes

**Categoría:** DevOps y cloud · **Nivel:** Intermedio · **Lectura:** 16 min
**Publicada:** 2026-07-28 · **Actualizada:** 2026-07-28 · **Autoría:** Underc0de
**Versión HTML (canónica):** https://underc0de.org/guias/devops-cloud/como-diagnosticar-errores-y-reinicios-de-pods-en-kubernetes/

## Respuesta rápida

Cuando un pod de **Kubernetes** no arranca o se reinicia sin parar, el estado que muestra kubectl get pods ya nombra el problema. Los más comunes: **CrashLoopBackOff** —el contenedor arranca y se cae una y otra vez, así que Kubernetes espera cada vez más entre reintentos; el fallo está *dentro* de la aplicación (una excepción al inicio, una variable que falta, una dependencia inalcanzable)—; **ImagePullBackOff** / **ErrImagePull** —no pudo descargar la imagen: nombre o etiqueta mal escritos, o falta autenticación al registro—; **OOMKilled** —el sistema mató el contenedor por superar su límite de memoria—; **Pending** —el pod no llegó a programarse en ningún nodo: no hay recursos, o un volumen o una restricción lo impiden—; y **CreateContainerConfigError** —falta un ConfigMap o Secret que el pod referencia—. El método para diagnosticar es siempre el mismo, tres comandos: kubectl describe pod (muestra los *eventos* al final, que suelen decir la causa exacta), kubectl logs (la salida de la aplicación; con --previous se ven los logs del contenedor *anterior* que se cayó) y kubectl get events (lo que pasó en el namespace). La regla de oro: **CrashLoopBackOff se diagnostica con los logs** (es la app); **ImagePullBackOff, Pending y los errores de config se diagnostican con describe** (es el entorno, no el código). Diagnosticar bien es leer el estado, ir a la herramienta correcta y no adivinar.

## Los estados de error

Esta guía profundiza en el **diagnóstico**; para los fundamentos, ver [Kubernetes para principiantes](../kubernetes-para-principiantes-pods-deployments-y-services/index.md). El primer paso siempre es kubectl get pods: la columna *STATUS* ya es media respuesta. Cada estado apunta a una **familia** de causas distinta.

| Estado | Qué significa | Familia de causas |
|---|---|---|
| CrashLoopBackOff | Arranca y se cae en bucle | Fallo dentro de la aplicación |
| ImagePullBackOff / ErrImagePull | No pudo descargar la imagen | Nombre/etiqueta o credenciales del registro |
| OOMKilled | Matado por exceder memoria | Límite de memoria demasiado bajo o fuga |
| Pending | No se programó en ningún nodo | Sin recursos, volumen o restricción |
| CreateContainerConfigError | Error al montar la configuración | Falta un ConfigMap o Secret referenciado |

> **La distinción que ahorra tiempo**
>
> La clave para no perderse es separar los fallos **del código** de los fallos **del entorno**. **CrashLoopBackOff** es casi siempre la *aplicación*: el contenedor sí se creó, pero el programa de dentro se cae —por eso se diagnostica con los **logs**—. **ImagePullBackOff**, **Pending** y **CreateContainerConfigError** son del *entorno*: el contenedor ni siquiera llegó a ejecutar tu código —por eso se diagnostican con **describe**, que cuenta qué impidió arrancarlo—. Saber en qué lado estás decide a qué herramienta ir.

## Dónde mirar

Tres comandos cubren casi todo el diagnóstico. Cada uno responde a una pregunta distinta:

```text
# 1. El estado y los EVENTOS del pod: por qué no arranca (fallos del entorno)
kubectl describe pod <nombre>      # mirar la sección "Events" al final

# 2. Los LOGS de la aplicación: por qué se cae (CrashLoopBackOff)
kubectl logs <nombre>
kubectl logs <nombre> --previous   # logs del contenedor ANTERIOR que ya murió

# 3. Los eventos del namespace, en orden: qué pasó y cuándo
kubectl get events --sort-by=.lastTimestamp
```

> **Atención**
>
> En un pod que se reinicia en bucle, cuando ejecutás kubectl logs a secas es probable que veas el contenedor *recién arrancado*, que aún no falló, o casi nada. El error que buscás está en la **ejecución anterior**, la que se cayó. kubectl logs <nombre> --previous muestra justamente esos logs del contenedor muerto: ahí aparece la excepción, el «no such file», el «connection refused» a la base de datos. Sin esa bandera, el CrashLoopBackOff parece un misterio; con ella, casi siempre se lee la causa en texto claro.

## Un método ordenado

Diagnosticar es no adivinar. Este orden lleva de «algo falla» a la causa concreta sin dar palos de ciego:

1. **Leé el estado.** kubectl get pods: el *STATUS* y el contador de *RESTARTS* ya acotan el problema.
2. **Describí el pod.** kubectl describe pod: la sección *Events* del final suele nombrar la causa (imagen, recursos, config).
3. **Si es un crash, mirá los logs.** kubectl logs --previous para ver por qué se cayó la aplicación.
4. **Confirmá la hipótesis.** ¿Es memoria? Revisá los límites. ¿Es config? Comprobá que exista el ConfigMap o Secret.
5. **Corregí en el manifiesto, no en el pod vivo.** Cambiá el deployment; Kubernetes recrea el pod con la corrección.

> **Atención**
>
> La tentación ante un pod caído es borrarlo para que se recree, esperando que «esta vez funcione». Si la causa no cambió —una imagen mal escrita, un secreto que falta, un límite de memoria bajo—, el pod volverá a fallar igual: reiniciar no arregla nada, solo reinicia el bucle. Y como los pods son efímeros, cualquier cambio hecho *dentro* de un pod vivo se pierde al recrearse. La corrección va en el **deployment** (o en el chart de Helm, o en el ConfigMap): la fuente declarativa. Kubernetes se encarga de aplicar el cambio recreando el pod.

## Errores frecuentes

- **Ver los logs sin --previous en un CrashLoopBackOff.** Se mira el contenedor recién arrancado, no el que se cayó.
- **Ignorar la sección *Events* de describe.** Es donde Kubernetes escribe la causa de los fallos del entorno.
- **Confundir fallo de imagen con fallo de app.** ImagePullBackOff es el registro; CrashLoopBackOff es tu código.
- **Reiniciar el pod esperando que se arregle solo.** Si la causa persiste, el fallo se repite; corregir la fuente.
- **Editar el pod vivo.** Los pods son efímeros; el cambio se pierde. Corregir el deployment o el chart.
- **No revisar los límites ante un OOMKilled.** El contenedor murió por memoria; ajustar el límite o el consumo.
- **Olvidar el namespace.** Un pod «que no aparece» suele estar en otro namespace; usar -n o -A.

## Preguntas frecuentes

**¿Qué significa CrashLoopBackOff?**
CrashLoopBackOff es uno de los estados de error más frecuentes en Kubernetes y significa que un contenedor dentro de un pod arranca y se cae de forma repetida, entrando en un bucle de reinicios. El nombre describe con precisión lo que ocurre: el contenedor sufre una caída, Kubernetes lo reinicia, vuelve a caerse, y ante estos fallos sucesivos Kubernetes aplica una espera creciente entre reintentos, es decir, un retroceso o backoff que aumenta el tiempo de espera para no reintentar sin descanso. La clave para entender este estado es que el problema está casi siempre dentro de la aplicación, no en el entorno de Kubernetes, porque el hecho de que el contenedor llegue a arrancar indica que la imagen se descargó y el contenedor se creó correctamente; lo que falla es el programa que corre dentro. Las causas típicas incluyen una excepción o un error en el arranque de la aplicación, la falta de una variable de entorno o de un fichero de configuración necesario, la imposibilidad de conectarse a una dependencia como una base de datos que aún no está disponible o cuya dirección es incorrecta, un comando de inicio mal definido, o que el proceso principal termina inmediatamente en lugar de quedarse ejecutándose. Debido a que el origen está en la aplicación, la forma correcta de diagnosticar un CrashLoopBackOff es mirar los registros del contenedor, y muy especialmente los registros de la ejecución anterior que se cayó, usando la opción que permite consultar los registros previos, ya que si se miran los registros del contenedor recién reiniciado es posible que aún no haya fallado y no muestre la causa. En esos registros previos suele aparecer en texto claro el motivo de la caída, como una excepción concreta, un archivo que no se encuentra o una conexión rechazada. Una vez identificada la causa, la corrección debe hacerse en la fuente declarativa, como el deployment, el chart o la configuración correspondiente, y nunca simplemente reiniciando el pod con la esperanza de que funcione, porque si la causa persiste el bucle se repetirá igual.

**¿Qué diferencia hay entre ImagePullBackOff y CrashLoopBackOff?**
ImagePullBackOff y CrashLoopBackOff son dos estados de error de Kubernetes que a veces se confunden pero que apuntan a problemas de naturaleza completamente distinta, y distinguirlos es fundamental para diagnosticar rápido. ImagePullBackOff, junto con el estado relacionado que indica un error al descargar la imagen, significa que Kubernetes no ha conseguido descargar la imagen del contenedor que el pod necesita, y por tanto el contenedor ni siquiera ha llegado a crearse ni a ejecutarse; se trata de un fallo del entorno, previo a cualquier ejecución del código de la aplicación. Sus causas habituales son que el nombre de la imagen o su etiqueta estén mal escritos, que la imagen no exista en el registro indicado, que el registro sea privado y falten las credenciales de acceso, o que haya problemas de conectividad con el registro. Como el problema es anterior a la ejecución del código, se diagnostica describiendo el pod y leyendo su sección de eventos, donde suele aparecer con claridad el motivo, como que la imagen no se encuentra o que la autenticación ha fallado. CrashLoopBackOff, en cambio, significa que la imagen sí se descargó y el contenedor sí se creó y arrancó, pero el programa que corre dentro se cae repetidamente, entrando en un bucle de reinicios con esperas crecientes; se trata de un fallo dentro de la aplicación. Sus causas suelen ser errores de arranque del programa, configuración faltante, dependencias inalcanzables o un proceso que termina de inmediato. Como el problema está en el código en ejecución, se diagnostica mirando los registros del contenedor, especialmente los de la ejecución anterior. En resumen, la diferencia esencial es que ImagePullBackOff es un problema del entorno que impide obtener la imagen y se investiga con la descripción del pod, mientras que CrashLoopBackOff es un problema de la aplicación que ya arrancó y se investiga con los registros; reconocer cuál de los dos estados muestra el pod indica de inmediato hacia dónde dirigir el diagnóstico y qué herramienta usar, evitando perder tiempo mirando en el sitio equivocado.

**¿Qué es OOMKilled y cómo se soluciona?**
OOMKilled es un estado que indica que un contenedor fue terminado por el sistema debido a que agotó la memoria, ya que las siglas hacen referencia a la condición de quedarse sin memoria. En Kubernetes, a los contenedores se les pueden asignar límites de memoria, y cuando un contenedor intenta usar más memoria de la que tiene permitida, el sistema operativo del nodo lo mata para proteger la estabilidad del resto, y Kubernetes marca ese contenedor como terminado por falta de memoria. Este estado suele aparecer reflejado en la descripción del pod, en la información del último estado del contenedor, indicando que la razón de la terminación fue quedarse sin memoria. Hay dos grandes causas posibles y, en consecuencia, dos enfoques de solución. La primera posibilidad es que el límite de memoria configurado para el contenedor sea sencillamente demasiado bajo para lo que la aplicación necesita legítimamente para funcionar; en ese caso, la solución consiste en aumentar el límite de memoria asignado en la configuración del contenedor, ajustándolo a un valor acorde al consumo real de la aplicación, siempre teniendo en cuenta la memoria disponible en el nodo. La segunda posibilidad es que la aplicación tenga un consumo de memoria anormal o creciente, por ejemplo debido a una fuga de memoria, a un procesamiento de datos ineficiente que carga demasiada información a la vez, o a una configuración interna inadecuada; en ese caso, subir el límite solo pospone el problema, y la solución correcta es investigar y corregir el consumo excesivo en la propia aplicación, por ejemplo optimizando el uso de memoria o solucionando la fuga. Para diagnosticar cuál de las dos situaciones se da, conviene observar el consumo de memoria de la aplicación a lo largo del tiempo, apoyándose en herramientas de observabilidad y métricas, y compararlo con el límite establecido. En resumen, ante un OOMKilled hay que decidir si el límite era injustamente bajo, en cuyo caso se aumenta, o si la aplicación consume de forma anómala, en cuyo caso se corrige el consumo, evitando la tentación de simplemente subir el límite sin entender la causa.

**¿Por qué un pod se queda en estado Pending?**
Un pod se queda en estado Pending cuando Kubernetes ha aceptado su creación pero todavía no ha conseguido asignarlo y ponerlo en marcha en ningún nodo del clúster, lo que significa que existe algún impedimento para su programación o para el arranque de sus contenedores. A diferencia de los estados en los que el contenedor ya intentó ejecutarse, el estado Pending indica que el problema es previo, y la forma de averiguar la causa concreta es describir el pod y leer su sección de eventos, donde el planificador de Kubernetes suele explicar por qué no ha podido ubicarlo. Las causas más habituales son varias. Una muy frecuente es la falta de recursos suficientes en el clúster: si el pod solicita una cantidad de CPU o de memoria que ningún nodo disponible puede satisfacer, el planificador no encuentra dónde colocarlo y el pod permanece pendiente hasta que haya recursos, lo que puede requerir liberar carga, ajustar las solicitudes de recursos del pod o añadir capacidad al clúster. Otra causa común está relacionada con el almacenamiento: si el pod necesita un volumen persistente que no se puede aprovisionar o enlazar, por ejemplo porque no hay almacenamiento disponible que cumpla los requisitos, el pod queda pendiente a la espera de ese volumen. También pueden impedir la programación las reglas de ubicación, como restricciones que exigen que el pod se coloque en nodos con determinadas características o etiquetas que no existen, marcas en los nodos que repelen los pods salvo que estos las toleren, o reglas de afinidad y antiafinidad que no se pueden cumplir con los nodos disponibles. En algunos casos, el problema puede ser que no haya nodos en estado listo en el clúster. Para resolver un pod en Pending, por tanto, lo primero es siempre describirlo y leer los eventos, que normalmente indican con claridad si el motivo es falta de recursos, un problema de volumen o una restricción de ubicación, y a partir de esa información se aplica la corrección adecuada, ya sea ajustar solicitudes de recursos, aprovisionar almacenamiento, revisar las reglas de ubicación o ampliar la capacidad del clúster.

**¿Qué comandos uso para diagnosticar un pod?**
Para diagnosticar por qué un pod falla o se reinicia en Kubernetes basta, en la gran mayoría de los casos, con un pequeño conjunto de comandos de la herramienta de línea de comandos del clúster, cada uno de los cuales responde a una pregunta distinta y se usa en un momento del diagnóstico. El primer comando es el que lista los pods, que muestra su estado y su número de reinicios; es el punto de partida, porque el estado indica la familia del problema y el contador de reinicios revela si el pod está en un bucle de caídas. El segundo comando fundamental es el que describe el pod en detalle, que ofrece una gran cantidad de información sobre su configuración y su historia reciente, y cuya sección de eventos, situada al final, suele indicar la causa exacta de los fallos del entorno, como no poder descargar la imagen, no encontrar recursos para programarlo o faltar un objeto de configuración; es la herramienta principal cuando el problema es previo a la ejecución del código. El tercer comando esencial es el que muestra los registros del contenedor, es decir, la salida de la aplicación, que es imprescindible cuando el problema está dentro del programa, como en un bucle de caídas; en ese caso resulta clave usar la opción que muestra los registros de la ejecución anterior que se cayó, porque los del contenedor recién reiniciado pueden no contener aún el error. Un cuarto comando muy útil es el que lista los eventos del espacio de nombres, preferiblemente ordenados por tiempo, para ver en conjunto qué ha ido ocurriendo. A estos se suman comandos complementarios según la necesidad, como el que permite abrir una sesión interactiva dentro de un contenedor en marcha para inspeccionarlo, el que muestra el consumo de recursos, o la posibilidad de consultar el estado detallado en formato estructurado. En cualquier caso, la recomendación metodológica es seguir siempre un orden: leer primero el estado, describir después el pod para revisar sus eventos, y acudir a los registros cuando el problema esté en la aplicación, dirigiéndose así directamente a la herramienta adecuada en lugar de adivinar. Con este puñado de comandos y este método ordenado, la mayoría de los problemas de pods se localizan en pocos minutos.

**¿Debo reiniciar el pod o corregir la configuración?**
Ante un pod que falla, la respuesta correcta es casi siempre corregir la causa en la configuración declarativa y no limitarse a reiniciar el pod, porque reiniciar sin más rara vez soluciona el problema y a menudo solo reinicia el bucle de fallos. La tentación de borrar un pod caído para que Kubernetes lo recree, esperando que esta vez funcione, es comprensible pero engañosa: si la causa subyacente no ha cambiado, por ejemplo si la imagen está mal referenciada, si falta un objeto de configuración o un secreto, si el límite de memoria es insuficiente o si la aplicación tiene un error de arranque, el pod recreado volverá a fallar exactamente igual, y lo único que se consigue es repetir el ciclo. Por eso el enfoque adecuado es diagnosticar primero la causa real mediante los comandos apropiados, identificar si el problema está en la aplicación o en el entorno, y aplicar la corrección en la fuente declarativa correspondiente, que según el caso será el objeto que gestiona el despliegue, el chart que lo generó, el objeto de configuración, el secreto o la definición de recursos. Hay además una razón técnica de peso para no intentar arreglar las cosas dentro de un pod en marcha: los pods son efímeros por diseño, de modo que cualquier cambio realizado directamente dentro de un pod vivo, como modificar un archivo o instalar algo manualmente, se perderá en cuanto ese pod se recree, algo que ocurre con normalidad en Kubernetes. La filosofía de Kubernetes es declarativa, lo que significa que uno describe el estado deseado en la configuración y el sistema se encarga de hacerlo realidad, recreando los pods según esa descripción; por tanto, la manera correcta de aplicar un cambio es modificar esa descripción y dejar que Kubernetes recree el pod con la corrección ya incorporada. En resumen, reiniciar un pod solo tiene sentido en casos muy concretos, como un fallo transitorio ya resuelto, pero como respuesta general ante un pod que falla lo procedente es diagnosticar la causa y corregirla en la configuración declarativa, no reiniciar a ciegas ni parchear el pod en vivo.

## Fuentes

Documentación oficial y material de la comunidad consultados para esta guía. Fecha de consulta: 28 de julio de 2026.

### Aportes de la comunidad Underc0de

1. **Underc0de, foro.** [Sección GNU/Linux](https://underc0de.org/foro/gnu-linux/). Kubernetes y contenedores.
2. **Underc0de, foro.** [Dudas y pedidos generales](https://underc0de.org/foro/dudas-y-pedidos-generales/). Infraestructura.

### Documentación oficial

1. **Kubernetes.** [Debug Pods](https://kubernetes.io/docs/tasks/debug/debug-application/debug-pods/). Guía oficial de diagnóstico de pods.
2. **Kubernetes.** [Pod Lifecycle](https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/). Fases y estados de un pod.
3. **Kubernetes.** [kubectl describe](https://kubernetes.io/docs/reference/kubectl/generated/kubectl_describe/). Referencia del comando.
4. **Kubernetes.** [Assign Memory Resources](https://kubernetes.io/docs/tasks/configure-pod-container/assign-memory-resource/). Límites de memoria y OOMKilled.

## Guías relacionadas

- [Kubernetes para principiantes](../kubernetes-para-principiantes-pods-deployments-y-services/index.md)
- [Instalar apps con Helm](../instalar-aplicaciones-en-kubernetes-con-helm/index.md)
- [Observabilidad](../observabilidad-con-opentelemetry-prometheus-y-grafana/index.md)
- [Docker desde cero](../docker-desde-cero-imagenes-contenedores-y-volumenes/index.md)
- [Índice de DevOps y cloud](../index.md)