Kubernetes · Cheatsheet 06

Problemas comunes

Buscá por el STATUS del Pod o por el texto del error. Cada tarjeta: qué ves → por qué pasa → cómo se arregla.

El camino de diagnóstico

Casi todo se resuelve con estos 3 comandos, en este orden.

✓

Y para el namespace entero: kubectl get events --sort-by=.lastTimestamp.

Estado del Pod

ImagePullBackOff / ErrImagePull

Failed to pull image "chanchito:latest": pull access denied, repository does not exist

Causa

La imagen no existe en el registry, el tag está mal, es privada, o es una imagen local y Kubernetes intenta bajarla de Docker Hub (pasa siempre con :latest).

Solución

Tag fijo + imagePullPolicy: IfNotPresent, y que la imagen esté en el nodo:

docker build -t chanchito:1 .
# minikube / kind:
minikube image load chanchito:1
kind load docker-image chanchito:1

Imagen privada: imagePullSecrets con un Secret docker-registry.

CrashLoopBackOff

chanchito-7d9f8-x2k4   0/1   CrashLoopBackOff   5 (32s ago)

Causa

El contenedor arranca y se cae una y otra vez: error en la app, variable faltante, no conecta a la DB, comando mal, o una livenessProbe que la mata.

Solución

# log del intento que murió
kubectl logs <pod> --previous
# Last State, Exit Code, probes
kubectl describe pod <pod>

Pending

0/1 nodes are available: 1 Insufficient memory.

Causa: El scheduler no encuentra un nodo: requests demasiado altos, PVC sin enlazar (unbound PersistentVolumeClaims) o taints en los nodos.
Solución: Leé el evento en kubectl describe pod. Bajá requests, dale más RAM a Docker Desktop, o revisá kubectl get pvc (tiene que estar Bound).

CreateContainerConfigError

Error: secret "mongo-secret" not found

Causa

El Pod referencia un Secret/ConfigMap (o una clave dentro) que no existe en ese namespace.

Solución

kubectl get secret,cm
kubectl describe secret mongo-secret

Crealo antes o corregí el nombre/clave. El Pod arranca solo cuando aparece.

OOMKilled (exit code 137)

Last State: Terminated   Reason: OOMKilled   Exit Code: 137

Causa: El contenedor superó limits.memory.
Solución: Subí el límite (ej. 512Mi) o reducí el consumo. Mirá el uso real con kubectl top pod.

Running pero 0/1 READY

Causa: La readinessProbe falla: path o puerto incorrecto, o la app tarda más que initialDelaySeconds. Mientras tanto el Service no le manda tráfico.
Solución: kubectl describe pod → “Readiness probe failed: …”. Corregí path/puerto o aumentá el delay.

Borro un Pod y vuelve a aparecer

Causa

Es de un Deployment: el estado deseado dice N réplicas y el controller lo recrea. No es un error.

Solución

# apagar sin borrar
kubectl scale deploy chanchito --replicas=0
# borrar de verdad
kubectl delete deploy chanchito

Pod trabado en Terminating

Causa

El proceso no responde a SIGTERM, el nodo se perdió, o un finalizer bloquea.

Solución

kubectl delete pod <pod> --grace-period=0 --force

Red y Services

El Service no responde (endpoints vacíos)

kubectl get endpoints chanchito
NAME        ENDPOINTS   AGE
chanchito   <none>      5m

Causa

El selector del Service no coincide con los labels de los Pods, o los Pods no están Ready.

Solución

kubectl get pods --show-labels
kubectl describe svc chanchito

Compará los labels con el campo Selector.Ver diagrama de labels.

connection refused a través del Service

Causa: Hay endpoints pero targetPort no es el puerto donde escucha la app (ej. 80 en vez de 3000), o la app escucha solo en 127.0.0.1.
Solución: targetPort = containerPort = puerto real. La app debe escuchar en 0.0.0.0. Probá directo: kubectl port-forward pod/<pod> 3000:3000.

ENOTFOUND monguito

getaddrinfo ENOTFOUND monguito

Causa

No existe un Service llamado así en el mismo namespace (el nombre del Deployment o del Pod no sirve como host).

Solución

kubectl get svc
kubectl run tmp --rm -it --image=busybox -- nslookup monguito

Si está en otro namespace: monguito.<namespace>.

localhost:30080 no abre

Causa

Depende del cluster: Docker Desktop publica NodePorts en localhost; minikube y kind no.

Solución

minikube service chanchito --url
# funciona en todos:
kubectl port-forward svc/chanchito 3000:80

nodePort fuera de rango

spec.ports[0].nodePort: Invalid value: 3000: provided port is not in the valid range. The range of valid ports is 30000-32767

Solución: Usá un valor entre 30000 y 32767, u omitilo para que se asigne solo.

Ingress devuelve 404 o no hace nada

Causa

No hay Ingress controller instalado, ingressClassName no coincide, o el host no es el que escribís en el navegador.

Solución

kubectl get ingressclass
kubectl describe ingress chanchito

port-forward: puerto ocupado

Unable to listen on port 3000: ... bind: address already in use

Solución: Otro proceso (¿tu docker compose?) usa ese puerto. Usá otro local: kubectl port-forward svc/chanchito 3001:80.

kubectl y YAML

No conecta al cluster

The connection to the server localhost:8080 was refused - did you specify the right host or port?

Causa

No hay cluster corriendo o no hay kubeconfig/contexto seleccionado.

Solución

Encendé Kubernetes en Docker Desktop (o minikube start) y:

kubectl config get-contexts
kubectl config use-context docker-desktop

No resources found

No resources found in default namespace.

Causa

Lo creaste en otro namespace o estás en otro contexto/cluster.

Solución

kubectl get pods -A
kubectl config current-context

Error de YAML / campo desconocido

error converting YAML to JSON: yaml: line 12: mapping values are not allowed in this context
strict decoding error: unknown field "spec.template.spec.contaners"

Causa

Indentación/tabs, o un nombre de campo mal escrito.

Solución

kubectl apply -f k8s/ --dry-run=server
kubectl explain deployment.spec.template.spec

field is immutable

The Deployment "chanchito" is invalid: spec.selector: Invalid value: ... field is immutable

Causa

Cambiaste el selector de un Deployment (o campos fijos de un Service/PVC) ya creado.

Solución

kubectl delete deploy chanchito
kubectl apply -f k8s/chanchito.yaml

selector no coincide con template

spec.template.metadata.labels: Invalid value: {"app":"chanchito"}: `selector` does not match template `labels`

Solución: spec.selector.matchLabels tiene que ser igual a spec.template.metadata.labels.

Config y datos

Cambié el ConfigMap/Secret y la app sigue igual

Causa

Las variables de entorno se leen solo al arrancar el contenedor.

Solución

kubectl rollout restart deploy/chanchito

Se perdieron los datos de Mongo

Causa: No había PVC (los datos estaban dentro del Pod), el mountPath no era /data/db, o kubectl delete -f k8s/ borró el PVC (con reclaimPolicy: Delete se borra el disco).
Solución: PVC + mountPath correcto. Para bajar la app sin perder datos, borrá solo los Deployments: kubectl delete deploy chanchito monguito.

Mongo: Authentication failed tras cambiar el Secret

Causa

Igual que en Docker: MONGO_INITDB_ROOT_* solo se aplica con el disco vacío. El PVC ya tenía el usuario viejo.

Solución

# ⚠ incluye el PVC: borra los datos
kubectl delete -f k8s/monguito.yaml
kubectl apply -f k8s/monguito.yaml

PVC en Pending

Causa

No hay StorageClass por defecto, o pediste un accessMode que no soporta (ej. ReadWriteMany en local).

Solución

kubectl get storageclass
kubectl describe pvc mongo-data

Una StorageClass tiene que figurar como (default).

No encontré ese problema. Probá con otra palabra del error o del STATUS.