Troubleshooting en Kubernetes: proceso paso a paso

Cuando algo falla en un cluster de Kubernetes lo peor que puedes hacer es lanzar comandos al azar. Tener un proceso ordenado para aislar el problema te ahorra horas y evita "soluciones" que en realidad solo mueven el síntoma.

A continuación dejamos el proceso que seguimos cuando un despliegue no se comporta como esperamos, junto con las principales categorías de errores que conviene revisar.

Proceso de resolución

1. Verifica el estado del Deployment

   kubectl get deployment <nombre> -n <ns>
   kubectl rollout status deployment/<nombre> -n <ns>

   ¿Los replicas deseados coinciden con los disponibles? Si no, sigue bajando.

2. Describe el Deployment

   kubectl describe deployment <nombre> -n <ns>

   La sección Conditions y los eventos al final suelen contar la historia: imagen inválida, problemas de selector, recursos insuficientes, etc.

3. Verifica los Pods (Ready / Estado)

   kubectl get pods -n <ns> -o wide

   Presta atención a STATUS (Pending, CrashLoopBackOff, ImagePullBackOff, Error, OOMKilled) y a la columna READY.

4. Revisa los logs del Pod

   kubectl logs <pod> -n <ns>
   kubectl logs <pod> -n <ns> --previous   # logs del contenedor anterior si crasheó
   kubectl logs <pod> -n <ns> -c <container>

5. Revisa al Kubelet del nodo Si los pods están Pending o sus contenedores no arrancan, conéctate al nodo y mira el kubelet:

   journalctl -u kubelet -f

6. Sube al Control Plane

   • ¿Hay pods del control plane en Pending o Error?

     kubectl get pods -n kube-system
   • Revisa logs del kube-apiserver, kube-controller-manager y kube-scheduler.
   • Confirma que hay recursos suficientes (CPU, memoria, disco) en los nodos.

Categorías de errores a revisar

Cuando el proceso anterior no te lleva a la causa, conviene barrer estas áreas:

• Errores desde la línea de comandos. ¿El recurso siquiera se aplicó? kubectl apply suele ser muy explícito.
• Logs y estado de los pods. Estado actual + logs previos suelen revelar fallos de configuración o de runtime.
• Shell dentro del pod para DNS y red.

  kubectl exec -it <pod> -- sh
  # dentro: getent hosts mi-servicio, curl, wget, etc.
• Logs del nodo y recursos disponibles. Capacidad insuficiente impide el scheduling.
• Seguridad: RBAC, SELinux o AppArmor. Pueden bloquear ServiceAccounts o llamadas al API. Verifica con:

  kubectl auth can-i <verbo> <recurso> --as=system:serviceaccount:<ns>:<sa>
• Llamadas al kube-apiserver. Los controllers comunican estado constantemente; un apiserver lento o sobrecargado afecta a todos.
• Habilitar auditoría. El audit log del apiserver es invaluable para reconstruir qué pasó.
• Red entre nodos, DNS y firewall. Comprueba que los nodos se ven entre sí en los puertos requeridos por el CNI y que CoreDNS está sano.

Resumen mental

Deployment → describe → Pods → logs → kubelet → control plane → red/DNS/RBAC.

Siempre de lo más alto a lo más bajo. Cuando un equipo nuevo adopta este patrón, la mayoría de los incidentes se resuelven sin necesidad de escalarlos.