Docker
Método sistemático para diagnosticar builds, arranque, red, storage y recursos.
Troubleshooting efectivo significa reducir el espacio de búsqueda con evidencia. No consiste en reiniciar, reconstruir o añadir hasta que el síntoma desaparezca.
--privilegedsíntoma
→ identificar frontera
→ formular hipótesis
→ obtener evidencia
→ cambiar una variable
→ verificar causa
→ corregir y prevenirDocker añade capas, pero también ofrece inspect, logs, events y objetos explícitos. El método correcto las recorre en orden.
1. cliente y context
2. daemon/host
3. registry e image
4. configuración de create
5. proceso/PID 1
6. filesystem y mounts
7. network/DNS/ports
8. resources/cgroups
9. aplicación y dependenciasNo investigues HTTP antes de demostrar que el proceso está running y escuchando.
Antes de actuar:
docker ps -a
docker inspect container > inspect.json
docker logs --timestamps container > container.log
docker events --since 30m > events.log
docker stats --no-stream > stats.txt
docker system df -v > disk.txtReiniciar puede:
Mitiga primero si existe riesgo para usuarios o datos, pero conserva lo posible.
Síntoma:
Cannot connect to the Docker daemonComprueba:
docker context show
docker context ls
docker version
docker infoPreguntas:
No cambies permisos del socket a world-writable. Controlar el daemon equivale normalmente a administración del host.
Revisa:
Comandos Linux conceptuales:
systemctl status docker
journalctl -u docker --since '30 min ago'
df -h
df -i
free -h
dmesg --ctime | tailEn Docker Desktop, añade recursos de la VM, diagnóstico de Desktop, VPN y filesystem sharing.
Tag/digest no existe o registry incorrecto.
La plataforma del daemon no está publicada.
Autenticación, scope o repository.
CA, hostname, proxy de inspección o clock.
Diagnóstico:
docker login registry.example.com
docker pull --platform linux/amd64 image
docker buildx imagetools inspect image
docker image inspect imageNo desactives TLS para “probar” en producción. Corrige confianza y hostname.
docker ps -a --filter name=api
docker inspect api --format '{{json .State}}'
docker logs apiDistingue:
0: terminó correctamente; quizá era un comando one-shot.1: error genérico de app.126: command encontrado pero no ejecutable/permisos.127: command no encontrado.137: SIGKILL; puede ser OOM, timeout o kill manual.139: segmentation fault.143: SIGTERM procesado como terminación.Los significados necesitan contexto. Correlaciona State, events y logs.
Inspecciona:
docker image inspect image --format '{{json .Config.Entrypoint}} {{json .Config.Cmd}}'
docker inspect api --format '{{json .Path}} {{json .Args}}'Problemas:
exec;Prueba:
docker run --rm --entrypoint /bin/sh imageSolo si la image tiene shell. En distroless usa debug image/container externo.
Causas:
file executable
uname -m
docker image inspect image --format '{{.Architecture}}'Revisa:
.dockerignore;docker create --name debug image
docker export debug | tar -tf - | head
docker rm debugNo imprimas secrets. Verifica nombres y presencia:
docker inspect api --format '{{json .Config.Env}}'Causas:
Ejecuta:
docker compose configcon cuidado de no publicar secretos.
Comprueba:
docker top api
docker logs api
docker inspect api --format '{{json .State.Health}}'Luego identifica listener:
docker exec api sh -c 'ss -lntp || netstat -lntp'Si no hay tooling, usa logs, endpoint interno o debug container.
Causas:
127.0.0.1;Diagnostica en capas.
docker network inspect backenddocker run --rm --network backend nicolaka/netshoot getent hosts dbdocker run --rm --network backend nicolaka/netshoot ip routedocker run --rm --network backend nicolaka/netshoot nc -zv db 5432curl -v http://api:3000/healthInterpreta:
no such host: DNS/network/name;connection refused: destino alcanzado, no listener;Dentro de un container apunta al mismo container. No a database, otro service ni host.
Usa service name para comunicación interna.
docker port api
docker inspect api --format '{{json .NetworkSettings.Ports}}'Comprueba:
0.0.0.0.Prueba desde:
Así localizas la frontera.
Síntoma: ciertos destinos fallan solo con VPN.
docker network inspect network
ip routeSi las subnets se superponen, coordina rangos. Reiniciar puede asignar otra red temporalmente, pero no corrige diseño.
Síntoma: ping o requests pequeños funcionan; TLS/payload grande falla.
Revisa MTU en host, bridge, VPN y overlay. Usa packet capture en entorno autorizado.
docker inspect api --format '{{json .Mounts}}'Problemas:
Distingue:
No escales directamente a root/privileged/777.
docker run --rm --mount type=volume,src=data,dst=/data alpine ls -lna /dataAntes de tocar nada:
docker compose ls
docker volume ls
docker inspect db --format '{{json .Mounts}}'
docker volume inspect volumeCausas:
down -v;No ejecutes prune.
df -h
df -i
docker system df -v
docker ps -a --sizeDistingue:
Libera solo después de identificar ownership y backup.
docker stats --no-stream api
docker inspect api --format '{{json .HostConfig}}'docker inspect api --format '{{.State.OOMKilled}}'
docker events --since 30mExit 137 no prueba OOM por sí solo.
Analiza:
Síntomas:
No confundas 100 % de la cuota con 100 % del host.
Errores resource temporarily unavailable, incapacidad de crear threads/procesos.
docker top apiCPU/memory normales pero latencia alta. Revisa disk latency, queue y database.
docker inspect api --format '{{json .State.Health}}'Problemas:
Unhealthy no siempre reinicia automáticamente. Comprende la plataforma.
docker ps -a
docker inspect api --format '{{.RestartCount}}'
docker logs --tail 200 apiDesactiva temporalmente la política o ejecuta una instancia de diagnóstico controlada. No dejes que el loop destruya logs o golpee dependencies.
Usa salida detallada:
docker buildx build --progress=plain --no-cache-filter stage .Revisa:
.dockerignore;Eso sugiere cache/input incorrecto, no que “Docker cache esté dañada” necesariamente.
Busca:
COPY incompleto;Corrige keys/dependencies; no desactives cache permanentemente.
docker compose config
docker compose ps --all
docker compose logs --tail 200
docker compose eventsCausas frecuentes:
Añade capas:
host macOS/Windows
→ Docker Desktop
→ Linux VM
→ daemon
→ containerInvestiga:
Que funcione en Desktop no garantiza Linux producción.
Compara explícitamente:
“Es el mismo código” no significa mismo sistema.
No uses producción como laboratorio.
Mantén runtime mínimo y una variante debug controlada con herramientas.
No instales paquetes dentro del container productivo durante incidente: altera evidencia e inmutabilidad.
Puedes conectar un debug container a la misma network o namespaces cuando la plataforma lo permite y el riesgo está controlado.
¿CLI conecta?
├─ no → context/socket/daemon
└─ sí
¿container fue creado?
├─ no → image/config/mount/network
└─ sí
¿PID 1 está running?
├─ no → exit/logs/signals/files
└─ sí
¿health/listener funciona?
├─ no → startup/app/resources
└─ sí
¿cliente alcanza?
├─ no → DNS/route/port/firewall
└─ sí → protocolo/dependency/businessUn incidente cerrado debe registrar:
“Se arregló reiniciando” no es causa raíz.
Pierde evidencia.
Cambia demasiadas variables y crea riesgo.
No distingue network interna.
Puede ser kill/timeout.
Puede borrar datos/cache necesarios.
Hace mutable la evidencia.
No sabes qué cambio resolvió.
inspect, logs, events y stats se complementan.--no-cache.Limpieza y administración de disco, donde liberar espacio debe hacerse con inventario, ownership y protección de datos.