Este es el capítulo que vas a releer. Kubernetes no esconde el problema: te da estados, eventos y logs. Lo difícil es saber en qué orden mirar.

Sello del curso: comandos válidos para Kubernetes 1.35. Sustituye nombres/namespaces por los tuyos.

El método en 6 pasos

1. ¿Qué está pasando? kubectl get pods -o wide
2. ¿Por qué? kubectl describe pod <pod> (mira los Events al final)
3. ¿La app se quejó? kubectl logs <pod> y --previous
4. ¿El nodo está saludable? kubectl describe node <node>, kubectl top
5. ¿La red/config está correcta? endpoints, DNS, secrets, probes
6. ¿Necesito entrar al pod? kubectl exec o kubectl debug

El estado cuenta la historia

Status	Primera pregunta	Comando
Pending	¿el scheduler pudo agendar?	describe pod → Events
ContainerCreating	¿imagen/volumen/CNI?	describe pod
ImagePullBackOff	¿la imagen existe/tiene acceso?	Events + imagePullSecrets
CrashLoopBackOff	¿por qué muere el proceso?	logs --previous
OOMKilled	¿se quedó sin memoria?	describe → Last State
RunContainerError	¿entrypoint/permiso?	logs, describe
Terminating	¿finalizer/PDB/nodo?	describe, get pdb
Completed	¿El Job terminó?	normal para Jobs

Pending

El pod fue creado, pero no fue agendado.

kubectl describe pod <pod> | tail -30

Causas comunes:

• Recursos insuficientes (Insufficient cpu/memory).
• nodeSelector/affinity imposible.
• Taint en el nodo sin toleration.
• PVC no vinculado (pod has unbound immediate PersistentVolumeClaims).
• Cuota del namespace agotada.
• Anti-affinity obligatoria sin nodo disponible.

Caso real: durante el mantenimiento de un worker, pods de Elasticsearch y RabbitMQ quedaron Pending porque la anti-affinity exigía un nodo por réplica y solo había dos nodos agendables. No era falta de recurso; era regla de distribución.

ContainerCreating y ImagePullBackOff

kubectl describe pod <pod> | grep -A6 Events

• Imagen inexistente/tag incorrecta: el registry responde 404.
• Registry privado: falta imagePullSecret.
• Rate limit: Docker Hub sin autenticación.
• Arquitectura incorrecta: imagen amd64 en nodo arm64.
• Imagen solo en caché en algunos nodos: si el pod es reagendado, falla.

Caso real: una imagen existía en caché en dos nodos y no en el tercero. Cuando el pod fue reagendado, entró en ErrImagePull. “Funcionaba” hasta que el nodo cambió.

CrashLoopBackOff

El contenedor inicia y muere. El log actual puede estar vacío; usa el anterior:

kubectl logs <pod> --previous
kubectl describe pod <pod> | grep -A5 'Last State'

Causas:

• Variable de entorno/secret ausente.
• Dependencia no disponible (base de datos, cola, DNS).
• Permiso de archivo/volumen.
• OOMKilled (límite de memoria).
• Liveness matando la app antes de terminar el boot.

Caso real: la app subía, Flyway aplicaba la migration y el guard de credenciales derribaba el proceso. El log actual solo mostraba el comienzo; el --previous mostró la excepción.

OOMKilled

kubectl describe pod <pod> | grep -i oom
kubectl top pod <pod>

Síntomas: Last State: Terminated, Reason: OOMKilled. Aumenta el límite con base en el uso real, no en la suposición. La memoria de JVM/Node necesita margen para off-heap.

Probes mal configuradas

• readinessProbe fallando: pod Running pero 0/1, fuera del Service.
• livenessProbe agresiva: reinicio en loop durante el boot.
• startupProbe ausente en app lenta: liveness mata antes de subir.

kubectl describe pod <pod> | grep -A4 -i probe

Red y DNS

kubectl -n <ns> get endpoints <service>
kubectl -n <ns> run dns --image=busybox:1.36 --rm -it --restart=Never -- nslookup <service>

Si el DNS falla, verifica CoreDNS y NetworkPolicy. Si el Service no tiene endpoints, el selector está incorrecto o el pod no está Ready.

Entrar al pod

kubectl exec -it <pod> -- sh
kubectl debug -it <pod> --image=busybox:1.36 --target=<container>

kubectl debug es útil cuando la imagen no tiene shell. Para nodos, kubectl debug node/<node> crea un pod privilegiado — úsalo con cuidado.

Eventos del cluster

kubectl get events -A --sort-by=.lastTimestamp | tail -30
kubectl -n <ns> get events --sort-by=.lastTimestamp

Los eventos expiran (1h por defecto). Si el problema fue ayer, necesitas logs/monitoreo, no get events.

Errores de permiso y admisión

• forbidden: RBAC del ServiceAccount.
• admission webhook denied: policy/PSA.
• failed quota: ResourceQuota.
• LimitRange: request/limit fuera de lo permitido.

kubectl auth can-i list pods --as=system:serviceaccount:<ns>:<sa>

Checklist de diagnóstico

• [ ] get pods -o wide (nodo, IP, restarts).
• [ ] describe pod con Events.
• [ ] logs y logs --previous.
• [ ] describe node y top.
• [ ] endpoints/DNS.
• [ ] secrets/configmaps/probes.
• [ ] eventos del namespace.
• [ ] RBAC/admission.

Glosario

• Event: registro efímero de decisión del cluster.
• BackOff: espera exponencial antes de nuevo intento.
• OOMKilled: muerte por límite de memoria.
• Ephemeral container: contenedor de diagnóstico adjunto al pod.
• Admission webhook: validación/mutación en la entrada de la API.

Siguiente

Temporada 1 concluida. En la Temporada 2 vamos a profundizar en storage, configuración, operadores y backup — comenzando por PV, PVC, NFS y local-path.

Siguiente: Curso Kubernetes 11 — Storage: PV, PVC, NFS y local-path