Troubleshooting y análisis de problemas en Kubernetes con kubectl

Sebastian Gomez

Apr 24, 2023

Updated: Jun 24, 2026

Troubleshooting y análisis de problemas en Kubernetes con kubectl

Como administrador de Kubernetes, me he encontrado con diversos problemas y retos al implementar y gestionar aplicaciones en clusters. En este artículo quiero compartir contigo mis experiencias y conocimientos en el uso de kubectl para solucionar problemas y analizar de manera efectiva tus aplicaciones de Kubernetes. A lo largo del post te mostraré cómo utilizar comandos esenciales de kubectl, interpretar los diferentes estados de los pods y realizar un diagnóstico eficiente de tus despliegues. También incluiré un diagrama para ilustrar el ciclo de vida de un pod, un resumen de cinco puntos al final, conclusiones y ejercicios prácticos para que puedas aplicar lo aprendido.

Comandos esenciales de kubectl para solucionar problemas

Para comenzar, es fundamental familiarizarse con los comandos básicos de kubectl que nos ayudarán a identificar y solucionar problemas en nuestros clusters de Kubernetes. Algunos de los comandos que utilizo con frecuencia incluyen:

`kubectl get`: este comando me permite obtener información sobre los objetos en mi cluster, como pods, servicios y otros componentes. Por ejemplo, puedo listar todos los pods y conocer su estado actual:

kubectl get pods

`kubectl describe`: cuando necesito más detalles sobre un objeto específico, recurro a kubectl describe. Por ejemplo, para obtener información detallada sobre el pod llamado my-pod-name:

kubectl describe pod my-pod-name

`kubectl exec`: este comando me permite ejecutar comandos y aplicaciones dentro de un pod en ejecución. Es importante incluir el separador --, que indica dónde terminan las opciones de kubectl y dónde empieza el comando que quieres correr dentro del contenedor:

# Ejecuta un comando puntual dentro del pod
kubectl exec my-pod-name -- ls /app

`kubectl logs`: cuando necesito ver lo que está sucediendo dentro de un pod, kubectl logs es una herramienta poderosa para analizar registros y mensajes de depuración de las aplicaciones en ejecución dentro de los pods:

kubectl logs my-pod-name

Estados de los pods y su significado

Los estados de los pods en Kubernetes me proporcionan información valiosa sobre el ciclo de vida y el rendimiento de mis aplicaciones. La fase del pod (campo status.phase) puede tomar uno de estos cinco valores:

Pendiente (Pending): el pod ha sido aceptado por Kubernetes, pero aún no se ha programado su ejecución o aún se están descargando las imágenes. Los contenedores todavía no están en marcha.
En ejecución (Running): el pod se ha asignado a un nodo y todos sus contenedores se han creado correctamente; al menos uno está en ejecución.
Exitoso (Succeeded): todos los contenedores del pod han terminado de ejecutarse con éxito y no se reiniciarán.
Fallido (Failed): uno o más contenedores del pod han terminado con errores y no se reiniciarán.
Desconocido (Unknown): no se puede obtener información sobre el estado del pod, probablemente debido a un error de comunicación entre el plano de control y el kubelet.

Aquí tienes el ciclo de vida representado como diagrama:

stateDiagram-v2
    [*] --> Pending
    Pending --> Running
    Running --> Succeeded
    Running --> Failed
    Pending --> Failed
    Pending --> Unknown
    Running --> Unknown
    Succeeded --> [*]
    Failed --> [*]

Estados de espera de los contenedores: lo que realmente verás al depurar

La fase del pod te da una visión general, pero en la práctica los problemas más comunes aparecen en los estados de espera de los contenedores individuales, que kubectl get pods muestra en la columna STATUS. Estos son los que más vas a encontrar:

`CrashLoopBackOff`: el contenedor arranca, falla, y Kubernetes lo reinicia una y otra vez con una espera creciente (backoff) entre intentos. Suele indicar un error en el comando de arranque, una variable de entorno faltante o una excepción al iniciar la aplicación. Revisa los logs con kubectl logs para ver la causa.
`ImagePullBackOff` y `ErrImagePull`: Kubernetes no pudo descargar la imagen del contenedor. Causas típicas: el nombre o tag de la imagen está mal escrito, el registro es privado y faltan las credenciales (un imagePullSecrets), o la imagen no existe.
`Pending` prolongado: si un pod se queda en Pending, normalmente es porque el scheduler no encuentra un nodo con recursos suficientes, hay un taint sin su toleration, o un PersistentVolumeClaim no se puede satisfacer. El comando kubectl describe pod te mostrará el evento exacto al final de la salida.

Interpretando la información de los pods y sus contenedores

Para comprender mejor lo que sucede dentro de mis pods y sus contenedores, utilizo el comando kubectl describe para obtener detalles adicionales, como etiquetas, requisitos de recursos y volúmenes. También me proporciona información sobre el estado del contenedor y del pod, como la cantidad de reinicios y la política de reinicio.

Conviene entender bien la política de reinicio (restartPolicy), porque es fácil malinterpretarla. Con restartPolicy: Always, el contenedor se reinicia cada vez que termina, sin importar si salió con éxito o con error; no significa que un contenedor sano y en ejecución se reinicie de forma continua. Las tres opciones disponibles son:

`Always` (por defecto): reinicia el contenedor siempre que termine, sea cual sea su código de salida. Es lo habitual para servicios de larga duración.
`OnFailure`: reinicia el contenedor solo si termina con un código de salida distinto de cero. Útil para procesos por lotes o jobs.
`Never`: no reinicia el contenedor nunca, termine como termine.

Cuando ves un contenedor reiniciándose sin parar (CrashLoopBackOff), no es que la política esté "mal", sino que el contenedor está fallando al arrancar y Always lo intenta una y otra vez. También puedo revisar los eventos al final de la salida del comando para identificar cualquier problema o cambio en el estado de mis contenedores y pods.

Ejecutando comandos y trabajando dentro de los contenedores

Cuando necesito solucionar problemas en una aplicación, puedo ejecutar comandos individuales en el contenedor utilizando kubectl exec con el separador --. Si necesito hacer más, como inspeccionar el sistema de archivos o probar la conectividad, puedo lanzar una shell interactiva usando las opciones -i y -t (abreviadas como -it), que conectan mi terminal al contenedor para que pueda trabajar dentro de él:

# Abre una shell interactiva dentro del contenedor
kubectl exec -it my-pod-name -- /bin/sh

Sin embargo, es importante recordar que instalar software directamente en un contenedor no es una buena práctica: esos cambios se pierden en cuanto el contenedor se reinicia. En su lugar, deberías crear imágenes de contenedor que contengan exactamente el software necesario y desplegarlas en consecuencia.

Revisando registros de pods y contenedores

Utilizo el comando kubectl logs para ver los registros de un pod. Si un pod tiene varios contenedores, puedo usar la opción -c para mostrar los registros de un contenedor específico dentro del pod:

# Logs de un contenedor concreto dentro de un pod con varios contenedores
kubectl logs my-pod-name -c my-container-name

Los registros contienen tanto la salida estándar como los mensajes de error de las aplicaciones en ejecución dentro del contenedor. Si el contenedor ya se reinició y quieres ver los logs de la instancia anterior (muy útil con CrashLoopBackOff), añade la opción --previous:

kubectl logs my-pod-name --previous

Resumen de cinco puntos clave

Familiarízate con los comandos esenciales de kubectl, como get, describe, exec y logs.
Aprende a interpretar los diferentes estados de los pods y, sobre todo, los estados de espera de los contenedores (CrashLoopBackOff, ImagePullBackOff), que son las señales reales de problemas.
Utiliza kubectl describe para obtener información detallada sobre tus pods y contenedores, incluidos los eventos y la política de reinicio.
Ejecuta comandos y trabaja dentro de los contenedores usando kubectl exec con --, y abre una shell con -it.
Revisa los registros de tus pods y contenedores con kubectl logs, usando -c para varios contenedores y --previous para la instancia anterior.

Conclusiones

Al utilizar kubectl de manera efectiva, puedes solucionar problemas y analizar tus aplicaciones de Kubernetes de forma eficiente. Entender los estados de los pods, los estados de espera de los contenedores y cómo interpretar la información que devuelven los comandos de kubectl es fundamental para mantener tus despliegues funcionando sin problemas.

Ejercicios prácticos

Utiliza kubectl get pods para ver el estado actual de todos los pods en tu cluster.
Elige un pod específico y utiliza kubectl describe pod para obtener más detalles sobre él, fijándote en la sección de eventos.
Ejecuta un comando simple dentro de un contenedor en ejecución usando kubectl exec my-pod-name -- <comando>.
Lanza una shell interactiva dentro de un contenedor con kubectl exec -it my-pod-name -- /bin/sh.
Revisa los registros de un pod específico utilizando kubectl logs, y prueba la opción --previous en un pod que haya reiniciado.

Eso es todo, espero que este post te sea de utilidad y lo puedas aplicar a algún proyecto que tengas en mente. Déjame un comentario si te sirvió, si quieres añadir alguna opinión o si tienes alguna duda. Y recuerda que si te gustó, también puedes compartirlo usando los links a las redes sociales aquí abajo.