kubectl debug: la guía completa para depurar pods y nodos

kubectl debug vs. kubectl logs vs. kubectl describe

kubectl debug, kubectl logs y kubectl describe son comandos de diagnóstico, pero cumplen propósitos distintos. kubectl logs recupera la salida de la aplicación, kubectl describe muestra los detalles y eventos de los recursos de Kubernetes, y kubectl debug brinda acceso interactivo para investigar en vivo.

kubectl logs

El comando kubectl logs muestra la salida de stdout y stderr de los contenedores. Se usa comúnmente para identificar fallos de la aplicación, errores de arranque o errores en tiempo de ejecución.

kubectl logs my-pod

Para pods con varios contenedores, especifica el nombre del contenedor:

kubectl logs my-pod -c app-container

Este comando es ligero y seguro, ya que no modifica el pod ni crea contenedores nuevos.

kubectl describe

El comando kubectl describe proporciona información detallada sobre los recursos de Kubernetes, incluidos labels, condiciones, volúmenes montados y eventos recientes.

kubectl describe pod my-pod

Este comando es útil para diagnosticar problemas como:

• Fallos de scheduling
• Errores al descargar imágenes
• Fallos de probes
• Restricciones de recursos
• Eventos de CrashLoopBackOff

A diferencia de kubectl logs, se centra en el estado de los objetos de Kubernetes y no en la salida de la aplicación.

kubectl debug

El comando kubectl debug habilita el diagnóstico interactivo adjuntando contenedores efímeros o creando pods temporales de debug.

kubectl debug my-pod -it --image=busybox

Este enfoque es útil cuando los logs y las descripciones de recursos no bastan. Por ejemplo, puedes:

• Inspeccionar la conectividad de red
• Examinar el contenido del sistema de archivos
• Ejecutar herramientas de inspección de procesos
• Depurar contenedores mínimos sin shell
• Investigar problemas a nivel de nodo

Como crea entornos temporales de depuración, kubectl debug ofrece un acceso más profundo que los otros comandos, minimizando a la vez los cambios en los workloads de producción.

Ejemplos prácticos de kubectl debug

Depurar la conectividad de red

Usa un contenedor de debug para probar el DNS, el descubrimiento de servicios y el acceso de red saliente desde el namespace de red del pod.

kubectl debug my-pod -it --image=busybox --target=my-container

Dentro del contenedor de debug, ejecuta comandos como:

nslookup kubernetes.default
wget -qO- http://my-service.default.svc.cluster.local
ping 10.0.0.10

Esto resulta útil cuando la imagen de la aplicación no incluye herramientas como nslookup, curl o ping.

Depurar un pod en CrashLoopBackOff

Para un pod que se reinicia constantemente, crea una copia para inspeccionarla. Así se evita alterar el workload original.

kubectl debug my-pod --copy-to=my-pod-debug -it --image=ubuntu

Desde el pod copiado puedes inspeccionar variables de entorno, archivos montados, configuración y acceso de red:

env
ls -la /etc/config
cat /etc/config/app.conf

Esto ayuda a identificar archivos faltantes, valores de entorno incorrectos o dependencias en tiempo de ejecución.

Depurar compartiendo el namespace de procesos

Comparte el namespace de procesos cuando necesites inspeccionar procesos de otro contenedor del pod.

kubectl debug my-pod \
  --copy-to=my-pod-debug \
  --share-processes \
  -it \
  --image=ubuntu

Dentro del contenedor de debug, revisa los procesos en ejecución:

ps aux
top

Es útil para inspeccionar procesos bloqueados, procesos zombis o procesos hijos inesperados.

Depurar con una imagen personalizada

Usa una imagen de debug personalizada cuando las imágenes estándar no incluyan las herramientas que necesitas.

kubectl debug my-pod -it \
  --image=my-registry.example.com/debug-tools:latest \
  --target=my-container

Una imagen personalizada puede incluir herramientas como curl, dig, tcpdump, strace o clientes de bases de datos. Así se mantienen pequeñas las imágenes de producción sin renunciar a un diagnóstico más profundo cuando hace falta.

Buenas prácticas al usar kubectl debug

Aquí tienes algunas prácticas útiles a tener en cuenta al usar este comando.

1. Empieza por la observabilidad antes de entrar al pod

Usa kubectl logs, kubectl describe, eventos, métricas y trazas antes de iniciar una sesión interactiva de debug. Estas herramientas son más rápidas y seguras, y muchas veces bastan para identificar el problema.

kubectl logs my-pod
kubectl describe pod my-pod
kubectl get events --sort-by=.metadata.creationTimestamp

Esto ayuda a confirmar si el problema se origina en la aplicación, el scheduling, los probes, los límites de recursos, la red o la configuración de Kubernetes. Por ejemplo, kubectl describe puede mostrar fallos al descargar imágenes, readiness probes fallidos o errores de montaje de volúmenes antes de que dediques tiempo a inspeccionar el contenedor directamente.

Usa kubectl debug cuando las señales disponibles no expliquen el problema o cuando necesites inspeccionar el estado en tiempo de ejecución desde dentro del entorno del pod.

2. Usa contenedores efímeros para inspeccionar, no para modificar la aplicación

Los contenedores efímeros están pensados para el diagnóstico. No los uses para parchear archivos, reiniciar servicios, instalar dependencias ni cambiar el comportamiento de la aplicación en un workload en ejecución.

Úsalos para inspeccionar el estado, ejecutar comandos de diagnóstico y recopilar evidencia:

kubectl debug my-pod -it --image=busybox --target=my-container

Por ejemplo, puedes comprobar la resolución de DNS, inspeccionar archivos montados, probar la conectividad de servicios o ver los procesos en ejecución. Estas acciones ayudan a entender qué está pasando sin alterar el workload.

Cualquier corrección debe hacerse en el código fuente, la imagen del contenedor, los manifiestos o el pipeline de despliegue. Así el comportamiento en producción se mantiene reproducible y se evitan cambios manuales puntuales que desaparecen cuando el pod se reinicia.

3. Prefiere los contenedores de debug antes que agregar herramientas a las imágenes de producción

Evita instalar shells, gestores de paquetes y herramientas de red en las imágenes de producción solo para el diagnóstico. Estas herramientas aumentan el tamaño de la imagen y pueden ampliar la superficie de ataque del contenedor.

En su lugar, mantén pequeñas las imágenes de la aplicación y usa una imagen de debug aparte cuando sea necesario:

kubectl debug my-pod -it --image=nicolaka/netshoot --target=my-container

Esto es especialmente útil con imágenes mínimas, como los contenedores distroless o basados en scratch, que a menudo no incluyen un shell. Un contenedor de debug puede aportar herramientas como curl, dig, tcpdump, ss e ip sin modificar la imagen de producción.

Este enfoque también mantiene una separación clara: la imagen de la aplicación ejecuta el workload, mientras que la imagen de debug se usa solo durante sesiones de diagnóstico controladas.

4. Usa imágenes de depuración aprobadas y seguras

Las imágenes de debug suelen incluir herramientas potentes como tcpdump, strace, curl, dig, gestores de paquetes y utilidades de shell. Usa únicamente imágenes aprobadas de registros confiables.

Fija las versiones de las imágenes en lugar de usar tags flotantes:

kubectl debug my-pod -it --image=registry.example.com/debug-tools:1.4.2

Las imágenes aprobadas deben escanearse en busca de vulnerabilidades y mantenerse actualizadas. Deben contener las herramientas que tus equipos realmente necesitan, sin paquetes innecesarios.

El acceso también debe controlarse con RBAC. No todos los usuarios deberían poder crear contenedores efímeros, adjuntarse a workloads sensibles o iniciar sesiones de debug a nivel de nodo. La depuración de nodos puede exponer sistemas de archivos del host e información a nivel de sistema, así que debe limitarse a operadores de confianza; combínala con el flag --profile (restricted o baseline) siempre que sea posible para no otorgar más acceso del que la sesión necesita.

5. Limpia los pods de debug y documenta la sesión

Elimina los pods de debug copiados una vez terminado el diagnóstico para evitar acumulación y consumo innecesario de recursos.

kubectl delete pod my-pod-debug

Los contenedores efímeros agregados a pods existentes no se pueden eliminar de la especificación del pod, pero dejan de ejecutarse cuando termina la sesión de depuración. Los pods copiados, en cambio, permanecen en el clúster hasta que se eliminan.

Registra qué se revisó, qué comandos se ejecutaron y qué se encontró. Esto facilita la revisión del incidente y ayuda a mejorar los runbooks para futuros problemas.

Unas buenas notas deben incluir el pod o nodo afectado, la imagen de debug utilizada, la salida importante de los comandos y la causa final. Así otros Engineers evitan repetir la misma investigación más adelante.

Reduce la depuración manual corrigiendo de forma proactiva los riesgos de resiliencia con PerfectScale

Comandos como kubectl debug son esenciales cuando necesitas investigar en tiempo real un pod que falla, un proceso bloqueado o un problema a nivel de nodo, pero la mayoría de esos incidentes se remontan a configuraciones incorrectas de recursos que podrían haberse detectado antes. PerfectScale mejora de forma autónoma la resiliencia y el rendimiento de Kubernetes mediante el right-sizing de los workloads, previniendo caídas y optimizando el uso de recursos para lograr una disponibilidad del 99.99%, de modo que tu equipo dedique menos tiempo a abrir sesiones interactivas de debug y más tiempo a lanzar producto. En lugar de esperar a que un pod falle para recurrir a los contenedores efímeros, PerfectScale identifica y corrige de raíz los riesgos de resiliencia que provocan esos fallos.

Capacidades clave de PerfectScale:

• Corrección automática de problemas: identifica y corrige al instante los riesgos de resiliencia para maximizar el tiempo de actividad y eliminar la latencia, previniendo errores de configuración (sin CPU request, sin memory request, sin memory limits) y problemas de aprovisionamiento insuficiente de recursos como OOM, CPU throttling y evictions.
• Fortalecimiento de la infraestructura: ofrece visibilidad integral de tus nodos para detectar de forma proactiva configuraciones incorrectas, prevenir la sobreasignación de nodos con recomendaciones precisas de memory limits, validar node affinities y taints, y elegir los tipos de nodo más adecuados para tus pods.
• Priorización basada en el impacto: enfoca a tu equipo en los problemas más críticos en tiempo real con priorización automática avanzada, y alinea las alertas con tus SLA y SLO para que los niveles de servicio se mantengan dentro del objetivo.
• Alertas en tiempo real e integraciones de ticketing: envía notificaciones instantáneas a través de Slack, MS Teams o Datadog, y te permite escalar cualquier problema a un flujo de trabajo establecido creando un ticket con un solo clic.
• Amplia cobertura de riesgos: detecta de forma continua evictions, errores de out of memory, sospechas de fugas de memoria, CPU throttling, reinicios de pods, HPA alcanzando el máximo de réplicas, y requests y limits de CPU y memoria insuficientes o sin definir.

Descubre cómo PerfectScale puede mantener estables tus clústeres y reducir la necesidad de diagnóstico manual en la plataforma de optimización de rendimiento de Kubernetes.

Preguntas frecuentes

¿Para qué sirve el comando kubectl debug?

kubectl debug sirve para diagnosticar workloads y nodos de Kubernetes de forma interactiva. Puede adjuntar un contenedor efímero a un pod en ejecución, crear una copia modificada de un pod que falla o lanzar un pod de debug en un nodo, todo sin necesidad de que la imagen objetivo incluya herramientas de depuración de fábrica.

¿Cómo uso kubectl debug en un pod?

Ejecuta kubectl debug <pod-name> -it --image=busybox para adjuntar un contenedor efímero de debug a un pod en ejecución. Agrega --target=<container-name> para compartir el namespace de procesos con un contenedor específico, o --copy-to=<new-pod-name> para depurar una copia en lugar del pod en vivo (útil con pods que fallan al arrancar).

¿Cómo uso kubectl debug en un nodo?

Ejecuta kubectl debug node/<node-name> -it --image=ubuntu para crear un pod de debug que se ejecuta en los namespaces del host del nodo con el sistema de archivos raíz del nodo montado en /host. Por defecto usa el perfil general, que no otorga acceso privilegiado; usa --profile=sysadmin si necesitas capacidades root completas.

¿Cuál es la sintaxis del comando kubectl debug?

La forma general es kubectl debug (POD | TYPE/NAME) [flags], usada habitualmente con --image para definir la imagen del contenedor de debug, -it para una terminal interactiva, --target para apuntar a un contenedor específico y --copy-to para depurar una copia del pod.

¿En qué se diferencia kubectl debug de kubectl exec?

kubectl exec ejecuta un comando dentro de un contenedor existente con la propia imagen del pod, así que solo funciona si esa imagen ya incluye las herramientas que necesitas. kubectl debug adjunta un contenedor (o pod) aparte con la imagen que elijas, algo esencial para contenedores mínimos o distroless que no tienen shell.

¿kubectl debug modifica el pod original o sus contenedores?

Agregar un contenedor efímero con kubectl debug no reinicia ni modifica los contenedores existentes del pod; solo agrega un contenedor temporal junto a ellos. Con --copy-to se va un paso más allá y se crea un pod aparte, dejando el original completamente intacto.

¿Debo limpiar los pods creados por kubectl debug?

Sí, en el caso de cualquier pod creado con --copy-to. Esos pods persisten en el clúster hasta que los eliminas con kubectl delete pod <debug-pod-name>. Los contenedores efímeros agregados directamente a un pod existente no requieren limpieza aparte: dejan de ejecutarse cuando termina la sesión, aunque siguen apareciendo en la especificación del pod.