Hands-on Lab

Healthchecks y políticas de reinicio en Docker (en la práctica, con docker run y Compose)

17 de julio de 2026 3 min

0 / 7

Chuleta

¿Te ha servido? No te pierdas el próximo lab

0:00 / 0:00

Levantamos un nginx:alpine con un HEALTHCHECK definido por línea de comandos, sin tocar la imagen. --health-cmd es lo que Docker ejecuta dentro del contenedor para decidir si está sano; --health-interval=2s marca cada cuánto se repite la comprobación; --health-timeout=2s es lo máximo que espera cada intento antes de darlo por fallido; --health-retries=3 son los fallos consecutivos necesarios para pasar a unhealthy; --health-start-period=2s da margen al arranque antes de contar los fallos como reales.

docker run -d --name web --health-cmd='wget -qO- http://localhost/ >/dev/null || exit 1' --health-interval=2s --health-timeout=2s --health-retries=3 --health-start-period=2s -p 8080:80 nginx:alpine

Lo hice yo

Comprobamos el estado de salud con docker inspect --format, leyendo directamente el campo State.Health.Status del contenedor. Tras el periodo de arranque y al menos una comprobación satisfactoria, debe mostrar 'healthy'.

sleep 5 && docker inspect --format '{{.State.Health.Status}}' web

La misma información, vista desde el comando que usamos a diario: docker ps añade '(healthy)' a la columna STATUS cuando el contenedor tiene un HEALTHCHECK definido y en verde. Confirmamos así, con dos comandos distintos, que web está sano.

docker ps --filter name=web --format 'table {{.Names}}\t{{.Status}}'

Provocamos un unhealthy a propósito: apuntamos --health-cmd al puerto 9999, donde nginx no escucha, así que wget fallará siempre. Con health-retries=2 y start-period=1s tardará solo unos segundos en declararse unhealthy, para verlo enseguida.

docker run -d --name web-bad --health-cmd='wget -qO- http://localhost:9999/ >/dev/null || exit 1' --health-interval=2s --health-timeout=2s --health-retries=2 --health-start-period=1s nginx:alpine

Lo hice yo

Confirmamos, con docker inspect y docker ps, que web-bad quedó en unhealthy tras agotar sus reintentos: docker no lo reinicia por sí solo, ni lo detiene; solo lo marca para que tú (o un orquestador) decidas qué hacer.

sleep 7 && docker inspect --format '{{.State.Health.Status}}' web-bad && docker ps -a --filter name=web-bad --format 'table {{.Names}}\t{{.Status}}'

En Compose, el healthcheck se escribe como un mapeo YAML (test/interval/timeout/retries/start_period) en vez de flags, con el mismo significado que en docker run. La clave está en app: depends_on.cache.condition: service_healthy, que bloquea el arranque de app hasta que cache reporte healthy, algo que un depends_on simple, solo de orden, no ofrece.

mkdir -p /root/lab && cat > /root/lab/compose.yaml <<'YAML'
services:
  cache:
    image: redis:alpine
    healthcheck:
      test: ['CMD', 'redis-cli', 'ping']
      interval: 2s
      timeout: 2s
      retries: 3
      start_period: 2s
    restart: unless-stopped
  app:
    image: alpine:3.20
    command: ['sh', '-c', 'echo App container starting now that cache is healthy; sleep 3600']
    depends_on:
      cache:
        condition: service_healthy
    restart: unless-stopped
YAML
cd /root/lab && docker compose up -d

Lo hice yo

docker compose ps muestra cache como '(healthy)' y app como Up; sus logs ya contienen el mensaje de arranque, la prueba de que Compose retuvo a app hasta que cache pasó su healthcheck, no antes.

cd /root/lab && sleep 6 && docker compose ps && echo '--- app logs ---' && docker compose logs app --no-color --tail=5

Levantamos un contenedor cuyo proceso principal termina siempre con exit 1, con --restart on-failure:5: Docker lo reinicia automáticamente cada vez que falla, con una espera creciente entre intentos, hasta un máximo de 5 veces. on-failure solo actúa sobre salidas con error; un exit 0 o un docker stop no lo dispara.

docker run -d --name flaky --restart on-failure:5 alpine:3.20 sh -c 'echo crashing on purpose; exit 1'

Lo hice yo

docker inspect expone RestartCount: un contador que Docker sube cada vez que reinicia el contenedor. Verlo por encima de cero, junto al Status, confirma que on-failure hizo su trabajo de verdad, no solo sobre el papel.

sleep 10 && docker inspect --format 'RestartCount={{.RestartCount}} Status={{.State.Status}}' flaky

Levantamos un contenedor con --restart unless-stopped para contrastarlo con always: ambos sobreviven a un fallo o a un reinicio del daemon, pero solo unless-stopped hace una excepción cuando el que para el contenedor eres tú.

docker run -d --name sticky --restart unless-stopped redis:alpine

Lo hice yo

Confirmamos que sticky está Up antes de tocarlo, para que el siguiente paso, pararlo a mano, sea una comparación limpia.

docker ps --filter name=sticky --format 'table {{.Names}}\t{{.Status}}'

Lo paramos nosotros, a propósito, con docker stop. Es una acción manual del usuario, no un fallo del proceso: la política unless-stopped trata este caso de forma distinta a un crash.

docker stop sticky

Lo hice yo

sticky sigue en Exited: unless-stopped respeta el docker stop manual y no lo revive. Con --restart always, en cambio, Docker lo habría vuelto a arrancar sin que se lo pidiéramos.

sleep 3 && docker ps -a --filter name=sticky --format 'table {{.Names}}\t{{.Status}}'

Desmontamos la pila de Compose (contenedores, red y volumen) y quitamos los cuatro contenedores sueltos que creamos durante el lab, para no dejar nada corriendo en el host desechable.

cd /root/lab && docker compose down --remove-orphans -v && docker rm -f web web-bad flaky sticky

Lo hice yo

Cerramos comprobando que no queda ningún contenedor: la lista está vacía y el contador final es 0, la prueba de que el lab deja el host tal y como lo encontró.

docker ps -a --format '{{.Names}}'; echo "remaining containers: $(docker ps -aq | wc -l)"

¿Te ha sido útil este lab? Puntúalo:

Click to rate this post!

[Total: 0 Average: 0]

Healthchecks y políticas de reinicio en Docker resuelven un problema que un simple docker ps no ve: que el proceso principal siga vivo no significa que esté sirviendo nada útil. Un servidor web puede quedarse colgado, sin caerse, y sin un HEALTHCHECK Docker no tiene forma de saberlo.

De starting a healthy o unhealthy

Un HEALTHCHECK se define con –health-cmd en docker run o con el campo healthcheck en un compose.yaml, y usa cuatro parámetros: el intervalo entre comprobaciones, el tiempo máximo por intento, el número de fallos consecutivos necesarios para pasar a unhealthy, y un periodo de arranque en el que los fallos todavía no cuentan. docker inspect –format ‘{{.State.Health.Status}}’ y la columna STATUS de docker ps muestran ese estado en cualquier momento.

Reinicios: no, on-failure, always y unless-stopped

La política de reinicio (–restart) es independiente del healthcheck: decide qué hace Docker cuando el proceso principal del contenedor termina. on-failure:N solo actúa sobre salidas con código distinto de cero y admite un tope de intentos; always y unless-stopped reinician también tras un fallo del propio daemon, pero unless-stopped respeta un docker stop manual y no vuelve a levantar el contenedor hasta que tú lo decidas.

service_healthy en Compose

Combinando ambas piezas, depends_on: condition: service_healthy en Compose retrasa el arranque de un servicio hasta que el healthcheck de su dependencia informa healthy, algo que un depends_on simple, que solo ordena los contenedores, no garantiza. Es la misma idea que ya vimos al montar healthchecks y reinicios en Docker Compose, aplicada aquí con comandos reales sobre un demonio Docker de verdad.

Si vienes de los fundamentos de Docker, este lab encaja con lo que cubrimos en volúmenes y bind mounts y en redes en Docker, y con el resto de guías de Herramientas. La referencia oficial de la instrucción vive en la documentación de Docker, la especificación abierta del campo healthcheck de Compose está en el repositorio de Compose Specification, y el comando que usamos para comprobar Redis está documentado en la referencia de Redis.

Preguntas frecuentes

¿Qué es un HEALTHCHECK en Docker?

Es un comando que Docker ejecuta dentro del propio contenedor a intervalos regulares (–health-interval, o el campo healthcheck en Compose) para decidir si el proceso está realmente sirviendo, no solo si el contenedor sigue en marcha. Si el comando falla health-retries veces seguidas, Docker marca el contenedor como unhealthy, sin reiniciarlo por sí solo.

¿Qué diferencia hay entre las políticas de reinicio on-failure, always y unless-stopped?

on-failure solo reinicia el contenedor cuando su proceso principal termina con un código distinto de cero, y admite un tope como on-failure:5. always reinicia siempre, también tras un docker stop manual o un reinicio del propio daemon, salvo que quites el contenedor. unless-stopped se comporta como always, pero respeta un docker stop explícito: no lo vuelve a levantar hasta que lo arranques tú o reinicies Docker.

¿Cómo usa Compose depends_on: condition: service_healthy?

Con ese ajuste, Compose no arranca el servicio dependiente hasta que el healthcheck del servicio del que depende reporte healthy, no solo hasta que su contenedor exista. Sin condition: service_healthy, depends_on únicamente ordena el arranque de los contenedores, sin ninguna garantía de que el primero esté realmente listo para recibir tráfico.

Chuleta

docker run -d --name web --health-cmd='wget -qO- http://localhost/ >/dev/null || exit 1' --health-interval=2s --health-timeout=2s --health-retries=3 --health-start-period=2s -p 8080:80 nginx:alpine

docker run -d --name web-bad --health-cmd='wget -qO- http://localhost:9999/ >/dev/null || exit 1' --health-interval=2s --health-timeout=2s --health-retries=2 --health-start-period=1s nginx:alpine

mkdir -p /root/lab && cat > /root/lab/compose.yaml <<'YAML'
services:
  cache:
    image: redis:alpine
    healthcheck:
      test: ['CMD', 'redis-cli', 'ping']
      interval: 2s
      timeout: 2s
      retries: 3
      start_period: 2s
    restart: unless-stopped
  app:
    image: alpine:3.20
    command: ['sh', '-c', 'echo App container starting now that cache is healthy; sleep 3600']
    depends_on:
      cache:
        condition: service_healthy
    restart: unless-stopped
YAML
cd /root/lab && docker compose up -d

docker run -d --name flaky --restart on-failure:5 alpine:3.20 sh -c 'echo crashing on purpose; exit 1'

docker run -d --name sticky --restart unless-stopped redis:alpine

```
docker stop sticky
```

cd /root/lab && docker compose down --remove-orphans -v && docker rm -f web web-bad flaky sticky

¿Te ha servido? No te pierdas el próximo lab

Suscríbete a la newsletter

De starting a healthy o unhealthy

Reinicios: no, on-failure, always y unless-stopped

service_healthy en Compose

Preguntas frecuentes

¿Qué es un HEALTHCHECK en Docker?

¿Qué diferencia hay entre las políticas de reinicio on-failure, always y unless-stopped?

¿Cómo usa Compose depends_on: condition: service_healthy?

Chuleta