Cuando algo falla en Kubernetes, el error visible rara vez es la causa real.
Muchas veces lo único que ves es:
CrashLoopBackOff Pending ImagePullBackOff 502 503 timeout
Pero detrás puede haber:
- storage roto - DNS interno - CNI - certificados - recursos - etcd - ingress - endpoints vacíos - readiness probes - nodos degradados - permisos - NetworkPolicies
Y precisamente ahí es donde mucha gente pierde muchísimo tiempo:
empieza mirando el sitio equivocado
Esta guía está pensada para revisar un clúster Kubernetes real desde el principio de forma ordenada:
pods eventos servicios endpoints ingress storage nodos logs estado general
No se trata de memorizar comandos.
Se trata de entender:
qué pregunta responde cada comprobación
Uno de los mayores errores:
kubectl delete pod
sin haber mirado nada.
Recrear el pod puede:
- borrar estado temporal - perder logs - ocultar el problema - mover el workload a otro nodo - destruir evidencias
Antes de tocar:
captura estado
La primera comprobación siempre debería ser:
kubectl get nodes -o wide
Preguntas:
¿Todos los nodos están Ready? ¿Hay nodos NotReady? ¿Hay nodos SchedulingDisabled? ¿Hay nodos desaparecidos? ¿Hay versiones mezcladas? ¿Hay problemas de red?
Ejemplo:
kubectl describe node NODO
Busca:
MemoryPressure DiskPressure PIDPressure NetworkUnavailable evictions
Muchos problemas aparentemente “de aplicación” empiezan realmente en nodos degradados.
kubectl get pods -A -o wide
Aquí no solo interesa si están Running.
Interesa detectar:
CrashLoopBackOff ImagePullBackOff Pending ContainerCreating Evicted Terminating infinito Completed inesperado OOMKilled
Y también:
en qué nodo está cada pod
Porque a veces:
todos los pods problemáticos están en el mismo nodo
kubectl get events -A --sort-by=.lastTimestamp
Este comando muchas veces ahorra muchísimo tiempo.
Aquí aparecen:
- errores scheduling - problemas de imagen - fallos de storage - mounts - probes - networking - certificados - CNI
Busca:
FailedScheduling FailedMount BackOff Unhealthy FailedCreatePodSandBox ErrImagePull ImagePullBackOff OOMKilled Evicted
Muchísima gente ignora eventos y empieza directamente a tocar pods.
Error enorme.
kubectl describe pod POD -n NAMESPACE
Aquí tienes:
- nodo - IP - imágenes - mounts - variables - eventos - probes - errores - reinicios
Preguntas clave:
¿Reinicia? ¿Cuántas veces? ¿La imagen existe? ¿Las probes fallan? ¿El volumen monta? ¿Tiene IP? ¿Tiene eventos recientes?
La parte de Events al final suele ser clave.
kubectl logs POD -n NAMESPACE
Si reinicia:
kubectl logs POD -n NAMESPACE --previous
Muchísima gente olvida:
--previous
Y precisamente ahí suele estar el error real antes del restart.
Buscar:
timeout panic connection refused permission denied segmentation fault OOM database unavailable DNS TLS
No es un error.
Es un síntoma.
El pod:
arranca falla reinicia falla reinicia
Causas típicas:
- variables incorrectas - secretos mal montados - dependencia caída - puerto incorrecto - permisos - configuración inválida - falta memoria - storage
Mirar:
kubectl logs --previous kubectl describe pod kubectl get events
Si un pod está Pending:
todavía no ha podido programarse
Causas habituales:
- falta CPU - falta memoria - taints - storage - affinity - nodeSelector - PVC sin bind
Comando clave:
kubectl describe pod POD -n NS
Y revisar eventos:
FailedScheduling
Muy típico.
Causas:
- imagen inexistente - tag incorrecto - registry caído - credenciales - DNS - proxy - CA interna
Comprobaciones:
kubectl describe pod POD -n NS kubectl get secrets -n NS kubectl describe secret REGISTRY_SECRET -n NS
En entornos enterprise:
certificados internos y proxies suelen romper pulls
kubectl get svc -A
Preguntas:
¿Existe el Service? ¿El puerto es correcto? ¿El selector coincide? ¿Es ClusterIP, NodePort o LoadBalancer?
Muchísimos problemas:
el Service existe pero no apunta a ningún pod
kubectl get endpoints -A
Esto es CRÍTICO.
Si el endpoint está vacío:
el tráfico no tiene backend real
Y eso suele generar:
502 503 timeout
Causas:
- labels incorrectas - selector incorrecto - readiness probe fallando - pod no Ready
Muchísima gente mira ingress antes que endpoints.
Error habitual.
Muy importantes.
Un pod puede estar:
Running
pero:
no Ready
Y entonces:
no recibe tráfico
Mirar:
kubectl describe pod POD -n NS
Buscar:
Readiness probe failed Liveness probe failed
Errores típicos:
- path incorrecto - puerto incorrecto - timeout muy bajo - aplicación lenta - dependencia no disponible
kubectl get ingress -A kubectl describe ingress NOMBRE -n NS
Revisar:
host path backend service TLS
Problemas típicos:
- ingress apunta a service incorrecto - service sin endpoints - certificado roto - DNS externo - ingress controller caído
También:
kubectl get pods -n ingress-nginx kubectl logs POD -n ingress-nginx
kubectl get pvc -A kubectl get pv
Buscar:
Pending Lost Failed
Muchísimos pods no arrancan por:
volúmenes no disponibles
Ejemplo:
kubectl describe pvc PVC -n NS
Problemas típicos:
- storage class inexistente - backend storage caído - permisos - NFS roto - Longhorn degradado - Ceph degradado
Muy importante.
Comprobar CoreDNS:
kubectl get pods -n kube-system kubectl logs -n kube-system deployment/coredns
Test rápido:
kubectl run dns-test --rm -it --image=busybox -- nslookup kubernetes.default
Muchos problemas de:
timeout connection refused
realmente son DNS interno roto.
kubectl top nodes kubectl top pods -A
Preguntas:
¿Hay nodos saturados? ¿Hay memoria al límite? ¿Hay CPU excesiva? ¿Hay pods enormes?
Buscar:
OOMKilled Evicted throttling
Si los pods no se comunican:
mirar CNI
Ejemplo:
kubectl get pods -n kube-system
Buscar:
calico flannel cilium canal multus
Errores típicos:
FailedCreatePodSandBox network plugin not ready failed to setup network
Logs:
kubectl logs POD -n kube-system
Si el clúster entero responde lento:
mirar control-plane
Especialmente:
etcd apiserver controller-manager scheduler
En RKE2:
journalctl -u rke2-server -n 200 --no-pager journalctl -u rke2-agent -n 200 --no-pager
Errores típicos:
context deadline exceeded etcd unhealthy certificate expired websocket close 1006 failed to reconcile
kubectl get nodes -o wide kubectl get pods -A -o wide kubectl get events -A --sort-by=.lastTimestamp kubectl get svc -A kubectl get endpoints -A kubectl get ingress -A kubectl get pvc -A kubectl top nodes kubectl top pods -A
Con solo eso:
muchas incidencias ya se orientan muchísimo
Supongamos:
usuarios reciben 503 en la aplicación
No empezaría reiniciando pods.
Primero:
kubectl get ingress -A kubectl get svc -A kubectl get endpoints -A
Si el endpoint está vacío:
el problema NO es ingress
Entonces:
kubectl get pods -n APP kubectl describe pod POD -n APP kubectl logs POD -n APP --previous
Si la readiness probe falla:
el pod está Running pero no recibe tráfico
Y ahí ya puedes buscar:
- dependencia - base de datos - configuración - DNS - certificados - timeout
mucho más rápido.
Diagnosticar Kubernetes no consiste en lanzar comandos aleatorios.
Consiste en:
- separar capas - validar estado real - mirar eventos - entender endpoints - revisar probes - revisar nodos - validar storage - revisar networking
Y especialmente:
entender qué significa realmente cada síntoma
Porque:
CrashLoopBackOff Pending 503 timeout
no son causas.
Son simplemente:
la forma que tiene Kubernetes de decirte que algo debajo está roto