Debug de contenedores

La premisa: los containers son procesos

Los containers son procesos del Linux host, no máquinas virtuales. Comparten kernel con el host y con otros containers. Eso significa que toda la tooling estándar de Unix funciona para debuggearlos, con algunos matices sobre namespaces y views.

Process output

docker container top

Forma más fácil de ver qué corre dentro de un container:

$ docker container run --rm -d --name nginx-debug nginx:latest
$ docker container top nginx-debug
UID   PID  PPID C STIME TTY TIME  CMD
root  2027 2002 0 12:35 ?   00:00 nginx: master process nginx -g daemon off;
uuidd 2085 2027 0 12:35 ?   00:00 nginx: worker process
uuidd 2086 2027 0 12:35 ?   00:00 nginx: worker process
…

ps desde el host

Como los containers son procesos del host, ps desde el host ve todo:

$ ps axlfww
… /usr/bin/containerd
… /usr/bin/dockerd -H fd:// --containerd=/run/containerd/containerd.sock
… \_ /usr/bin/docker-proxy -proto tcp -host-ip 0.0.0.0 -host-port 8080 \
       -container-ip 172.17.0.2 -container-port 8080
… \_ /usr/bin/docker-proxy -proto tcp -host-ip :: -host-port 8080 \
       -container-ip 172.17.0.2 -container-port 8080
…
… /usr/bin/containerd-shim-runc-v2 -namespace moby -id 97…3d …
… \_ sleep 120
… /usr/bin/containerd-shim-runc-v2 -namespace moby -id 69…7c …

Cada containerd-shim-runc-v2 representa un container. Cada docker-proxy mapea puertos del host al container. El tree view te dice qué proceso vive en qué container.

Process inspection

Si tienes shell en el host, toda la tooling Unix estándar funciona:

# strace sobre un proceso del container
$ sudo strace -p 23032
# epoll_pwait(10, …

# lsof muestra archivos y sockets abiertos
$ sudo lsof -p 22983
# COMMAND   PID USER … NAME
# nginx   22983 root … /
# nginx   22983 root … /usr/sbin/nginx
# …

# gdb (GNU debugger)
sudo gdb -p 22983

Container de debug con acceso a otro container

Para casos avanzados, puedes correr un container que ve los procesos de otro:

$ docker container run -ti --rm --cap-add=SYS_PTRACE \
    --pid=container:nginx-debug \
    spkane/train-os:latest bash

# Dentro: ps aux ve los procesos de nginx-debug
[root@e4b5d2f3a3a7 /]# ps aux
USER  PID  %CPU %MEM  …  COMMAND
root  1    0.0  0.2  …  nginx: master process
101  30   0.0  0.1  …  nginx: worker process
101  31   0.0  0.1  …  nginx: worker process
root  136  0.1  0.1  …  bash
root  152  0.2  0.2  …  ps aux

--pid=container:nginx-debug comparte el PID namespace. --cap-add=SYS_PTRACE permite strace y gdb sobre los procesos del otro container.

Controlling processes

PID 1 es especial

En Unix, PID 1 (init) es responsable de reapar hijos (zombie processes). En un container sin init system, tu main process es PID 1. Si tu proceso spawn-ea hijos y no los reapa, se acumulan zombies.

# Sin --init: tu CMD es PID 1
$ docker container run --rm -it alpine:3.16 sh
/ # ps -ef
PID   USER     TIME  COMMAND
    1 root      0:00  sh   ← tu CMD es PID 1
    5 root      0:00  ps -ef

# Con --init: tini es PID 1
$ docker container run --rm -it --init alpine:3.16 sh
/ # ps -ef
PID   USER     TIME  COMMAND
    1 root      0:00  /sbin/docker-init -- sh   ← tini maneja PID 1
    5 root      0:00  sh
    6 root      0:00  ps -ef

tini es un init minimalista que reapa hijos. Úsalo en producción si tienes procesos que fork-ean. La alternativa es un init system completo (s6, runit, supervisord), pero eso añade peso.

Signals

docker container kill -s <SIGNAL> envía Unix signals al PID 1 del container. Ejemplos:

# SIGTERM (default) - pide al proceso que termine limpiamente
docker container kill nginx-debug

# SIGUSR1 - nginx reopen logs (lo lee de su config)
docker container kill -s SIGUSR1 nginx-debug

# SIGHUP - reload config
docker container kill -s SIGHUP nginx-debug

Network inspection

$ docker network ls
NETWORK ID     NAME      DRIVER    SCOPE
f9685b50d57c   bridge    bridge    local
8acae1680cbd   host      host      local
fb70d67499d3   none      null      local

$ docker network inspect bridge
[
  {
    "Name": "bridge",
    "Containers": {
      "69e9…c87c": {
        "Name": "cadvisor",
        "IPv4Address": "172.17.0.2/16",
        ...
      }
    }
  }
]

Desde el host

netstat desde el host muestra los puertos bindeados por docker-proxy:

$ sudo netstat -anp
# tcp  0  0  0.0.0.0:8080  0.0.0.0:*  LISTEN  1516/docker-proxy
# tcp6 0  0  :::8080        :::*      LISTEN  1522/docker-proxy

Cada docker-proxy por container-port mapeado (uno IPv4, otro IPv6).

Debugging shell-less containers

Las imágenes minimalistas (como FROM scratch) no tienen shell. No puedes hacer docker container exec /bin/bash ni nsenter. Para esas imágenes:

Opción 1: image de debug temporal

# Build un image de debug basado en el binario de tu app
FROM scratch
COPY --from=builder /helloworld /helloworld
CMD ["/helloworld"]

# Si necesitas herramientas, crea un image paralelo con busybox
docker container run -ti --rm \
  --pid=container:<container_id> \
  --network=container:<container_id> \
  busybox sh

Esto comparte el PID namespace y network namespace con el container shell-less. Dentro, puedes correr ps, netstat, wget, nc, etc.

Opción 2: nsenter al PID 1

# Encuentra el PID del container en el host
PID=$(docker container inspect --format '{{.State.Pid}}' <container_id>)

# Entra al container
sudo nsenter -t $PID -m -u -n -i -p
# -m: mount namespace
# -u: UTS namespace (hostname)
# -n: network namespace
# -i: IPC namespace
# -p: PID namespace

Dentro de nsenter tienes un shell “del container” sin necesidad de que el container tenga uno.

Debugging interactivo (lo básico)

Para la mayoría de casos en desarrollo, docker container exec es suficiente:

# Lanza un container con tu app
docker container run -d --name mi-app my-image

# Entra a un shell
docker container exec -it mi-app /bin/bash
# ...investiga...

# O corre un comando puntual
docker container exec mi-app ls /app
docker container exec mi-app cat /var/log/app.log
docker container exec mi-app ps aux

Cuándo usar qué

Próximos pasos

• 09-docker-compose: archivos docker-compose.yml, servicios múltiples, networks y volumes, profiles, override, y patrones de uso.