DevOps · 04

Diagnóstico por capas

Cuando “no anda”, el problema está en una capa. Revisalas de abajo hacia arriba: imagen → plataforma → Pod → red. Los ejemplos usan el proyecto completo.

Términos de esta página

Capa
Cada nivel del proyecto: la imagen (Docker), la plataforma (Terraform), los Pods (Kubernetes) y la red que los conecta.
Contexto (kubectl)
A qué cluster apuntan kubectl y Terraform. Si apuntan a clusters distintos, uno crea cosas donde el otro no mira.
Events
Los avisos que Kubernetes registra sobre cada objeto. Están al final de kubectl describe y suelen explicar el problema.
Endpoints
Los Pods a los que un Service le está mandando tráfico. Vacío = el Service no encuentra Pods listos.
Drift
Cuando alguien cambia a mano algo que administra Terraform y el código ya no coincide con la realidad.
Tag de imagen
La versión de la imagen (chanchito:1.0.0). Reusar el mismo tag para código nuevo es causa frecuente de “no veo mis cambios”.
0

El camino de diagnóstico

Cuatro preguntas. La primera que contesta “no” te dice dónde mirar.

1 · ¿La imagen corre sola? docker run --rm -e MONGO_URL=… chanchito:1.0.0 2 · ¿Existe la plataforma? terraform -chdir=infra plan → No changes 3 · ¿Los Pods están Running y Ready? kubectl get pods -n chanchito 4 · ¿El Service tiene endpoints? kubectl get endpoints -n chanchito sí sí sí no Docker: Dockerfile, dependencias, código docker logs · docker run -it … sh no Terraform: contexto, namespace, Secret terraform apply · state list no Kubernetes: imagen, config, probes, recursos describe pod (Events) · logs --previous no Red: selector, puertos, nombres describe svc · port-forward al Pod
✓

Si las cuatro dan “sí” y aun así falla, el problema está en la aplicación (lógica, datos): mirá los logs de los Pods.

1

Comandos de diagnóstico por capa

Los primeros que conviene correr en cada una.

Docker 
docker images chanchito
¿Existe la imagen con ese tag?
docker run --rm -it chanchito:1.0.0 sh
Entrar a la imagen y mirar los archivos.
docker compose logs -f chanchito
El error de la app en desarrollo.
Terraform 
terraform -chdir=infra plan
“No changes” = la plataforma está como el código.
terraform -chdir=infra state list
Qué administra Terraform.
kubectl config current-context
¿Terraform y kubectl apuntan al mismo cluster?
Kubernetes 
kubectl get all,secret,cm,pvc -n chanchito
Todo lo del namespace de un vistazo.
kubectl describe pod -n chanchito <pod>
Leé los Events del final.
kubectl get events -n chanchito --sort-by=.lastTimestamp
Qué pasó, en orden.
2

Capa Docker: la imagen

npm ci falla en el build

npm error The `npm ci` command can only install with an existing package-lock.json
Solución
Generá y commiteá el lock: npm install en app/. O usá npm install --omit=dev en el Dockerfile (menos reproducible).

MONGO_URL undefined

MongooseError: The `uri` parameter to `openUri()` must be a string, got "undefined"
Causa
La variable no llega: falta .env en Compose, o el env del Deployment no apunta a la clave correcta del Secret.
Comprobar
docker compose config
kubectl exec -n chanchito deploy/chanchito -- printenv MONGO_URL

Cambié el código y sigue igual

Causa
Reconstruiste con el mismo tag: Kubernetes ya tiene esa imagen y no la vuelve a mirar (IfNotPresent).
Solución
Tag nuevo en cada versión (1.0.1) y kubectl set image. En Compose: up --build.
3

Capa Terraform: la plataforma

No llega al cluster

Error: Kubernetes cluster unreachable
Error: context "docker-desktop" does not exist
Causa
Kubernetes de Docker Desktop apagado, o el contexto se llama distinto.
Solución
kubectl config get-contexts
Usá ese nombre en config_context del provider.

El namespace ya existe

Error: namespaces "chanchito" already exists
Causa
Lo creaste antes a mano con kubectl; Terraform no lo administra.
Solución
Importalo (o borralo si está vacío):
import {
  to = kubernetes_namespace_v1.app
  id = "chanchito"
}

El plan quiere cambiar el Secret

Causa
Alguien lo editó con kubectl (drift) o cambió TF_VAR_mongo_password en tu terminal.
Solución
Lo que administra Terraform se cambia solo con Terraform. Revisá la variable y aplicá; después kubectl rollout restart.

destroy se queda esperando

Causa
El namespace queda en Terminating mientras borra lo que tiene adentro (Pods, PVC).
Solución
Bajá primero la app: kubectl delete -n chanchito -f k8s/, y después terraform destroy.
4

Capa Kubernetes: los Pods

ImagePullBackOff

Failed to pull image "chanchito:1.0.0": pull access denied
Causa
El cluster no tiene la imagen local: tag mal escrito, imagePullPolicy: Always, o Docker Desktop en modo kind.
Solución
docker images chanchito para ver los tags; imagePullPolicy: IfNotPresent; o subí la imagen a un registry.

CreateContainerConfigError

Error: secret "mongo" not found
Causa
Aplicaste k8s/ antes que Terraform, o en otro namespace (te faltó -n chanchito).
Solución
kubectl get secret -n chanchito
terraform -chdir=infra apply
El Pod arranca solo cuando aparece el Secret.

CrashLoopBackOff en chanchito

Causa típica
No conecta a Mongo (todavía arrancando, contraseña distinta) o una livenessProbe que falla.
Solución
kubectl logs -n chanchito <pod> --previous
Si es Authentication failed, mirá la tarjeta de abajo.

Mongo: Authentication failed

Causa
Cambiaste la contraseña, pero Mongo solo usa MONGO_INITDB_* con el disco vacío: el usuario viejo sigue en el PVC (o en el volumen de Compose).
Solución
Para empezar de cero (⚠ borra los datos):
kubectl delete -n chanchito -f k8s/mongo.yaml
kubectl apply  -n chanchito -f k8s/mongo.yaml
En Compose: docker compose down -v.

Running pero 0/1 READY

Causa
La readinessProbe no recibe 200 en /health: la app no tiene esa ruta (imagen vieja) o tarda en arrancar.
Solución
kubectl describe pod → “Readiness probe failed”. Reconstruí con el app.js nuevo y un tag nuevo.
5

Red: de tu navegador a la base

localhost:30080 no responde

Revisar
  • kubectl get svc -n chanchito: ¿dice 80:30080/TCP?
  • kubectl get endpoints -n chanchito chanchito: si está vacío, los Pods no están Ready o el selector no coincide.
  • Probá directo al Pod: kubectl port-forward -n chanchito deploy/chanchito 3000:3000.

ENOTFOUND monguito

getaddrinfo ENOTFOUND monguito
Causa
El Service de Mongo no existe en ese namespace, o se llama distinto que el host de MONGO_URL.
Solución
kubectl get svc -n chanchito
El nombre del Service y el host de la URL tienen que coincidir.

Compose y Kubernetes a la vez

Qué pasa
Pueden convivir: Compose usa el puerto 3000 y Kubernetes el 30080. Lo que no comparten son los datos: cada uno tiene su propia base.
Tip
Si un puerto está ocupado: netstat -ano | findstr :3000.

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