Configuración de Docker Health Check para Confiabilidad
Configura HEALTHCHECK de Docker con curl, wget o scripts propios para detectar contenedores que dejan de responder, no solo los que fallan.
Visión General
Tu contenedor puede mostrar Up 3 hours en docker ps y aun así ser inservible. El proceso está vivo, pero la app dentro está en deadlock, sin memoria o atascada en una conexión muerta — y cada petición termina en timeout. Docker solo no puede notar la diferencia, porque “contenedor arriba” solo significa que el proceso principal existe.
Ahí es donde encaja HEALTHCHECK: le dice a Docker que pruebe la aplicación, no solo el proceso. De forma periódica, Docker ejecuta un comando dentro del contenedor y reporta starting, healthy o unhealthy — visible en docker ps y docker inspect.
Algo que conviene saber de entrada: docker run normal no reinicia contenedores unhealthy. El estado es informativo salvo que algo actúe sobre él — Docker Swarm reemplaza las tareas unhealthy, los stacks de Compose lo combinan con políticas de reinicio o un sidecar autoheal, y Kubernetes ignora HEALTHCHECK por completo en favor de su propio sistema de probes (cubierto en el patrón de health check). Si necesitas el endpoint /health en sí, implementa primero el endpoint de health check.
Cuándo Usar
- Ejecutas contenedores en producción y necesitas que la plataforma detecte fallos a nivel de aplicación, no solo caídas de proceso
- Usas Docker Swarm y quieres que las tareas unhealthy se reemplacen automáticamente
- Quieres que
docker psmuestre el estado de salud para verificaciones manuales o por script - Tu app puede estar corriendo pero sin responder (deadlocks, agotamiento de memoria, conexiones atascadas)
- Usas Compose y quieres
depends_on: condition: service_healthypara ordenar el arranque
Cuándo No Usarlo
- En pods gestionados por Kubernetes — Kubernetes ignora
HEALTHCHECK; define probes de liveness, readiness y startup en el pod spec en su lugar - Para contenedores one-shot o de batch — no hay un proceso de larga duración que sondear
- Cuando el único consumidor del estado de salud es un balanceador de carga externo — apunta el LB directamente a tu endpoint de health en lugar de duplicar verificaciones
Solución
El patrón es siempre el mismo: un comando barato que sale con código 0 cuando la app está bien y con código distinto de cero cuando no. Elijas lo que elijas, que sea algo ya incluido en la imagen.
HEALTHCHECK básico con curl
FROM node:20-alpine
WORKDIR /app
COPY . .
RUN npm ci --omit=dev
HEALTHCHECK --interval=30s --timeout=5s --retries=3 --start-period=10s \
CMD curl -f http://localhost:3000/health || exit 1
EXPOSE 3000
CMD ["node", "server.js"]
HEALTHCHECK con wget (imágenes Alpine sin curl)
FROM node:20-alpine
WORKDIR /app
COPY . .
RUN npm ci --omit=dev
HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
CMD wget --no-verbose --tries=1 --spider http://localhost:3000/health || exit 1
EXPOSE 3000
CMD ["node", "server.js"]
HEALTHCHECK con script propio
FROM python:3.12-slim
WORKDIR /app
COPY . .
RUN pip install --no-cache-dir -r requirements.txt
COPY healthcheck.sh /healthcheck.sh
RUN chmod +x /healthcheck.sh
HEALTHCHECK --interval=30s --timeout=10s --retries=3 --start-period=15s \
CMD /healthcheck.sh
EXPOSE 8000
CMD ["gunicorn", "app:app", "--bind", "0.0.0.0:8000"]
#!/bin/bash
# healthcheck.sh
set -e
# Verificar si el endpoint HTTP responde
response=$(curl -s -o /dev/null -w "%{http_code}" http://localhost:8000/health)
if [ "$response" = "200" ]; then
exit 0
else
echo "Health check falló: HTTP $response"
exit 1
fi
HEALTHCHECK para PostgreSQL
FROM postgres:16-alpine
HEALTHCHECK --interval=10s --timeout=5s --retries=5 \
CMD pg_isready -U postgres -d mydb || exit 1
HEALTHCHECK para Redis
FROM redis:7-alpine
HEALTHCHECK --interval=10s --timeout=3s --retries=3 \
CMD redis-cli ping | grep PONG || exit 1
Healthcheck en Docker Compose con depends_on
# docker-compose.yml
services:
api:
build: .
ports:
- "3000:3000"
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
interval: 30s
timeout: 5s
retries: 3
start_period: 10s
worker:
build: ./worker
depends_on:
api:
condition: service_healthy
redis:
condition: service_healthy
redis:
image: redis:7-alpine
healthcheck:
test: ["CMD", "redis-cli", "ping"]
interval: 10s
timeout: 3s
retries: 3
Endpoint de health en Node.js
const http = require("http");
const server = http.createServer((req, res) => {
if (req.url === "/health" && req.method === "GET") {
res.writeHead(200, { "Content-Type": "application/json" });
res.end(JSON.stringify({ status: "healthy" }));
return;
}
// ... otras rutas
});
server.listen(3000);
Endpoint de health en Python (FastAPI)
from fastapi import FastAPI
app = FastAPI()
@app.get("/health")
async def health():
return {"status": "healthy"}
Explicación
Opciones
Cinco flags controlan cuándo y cómo Docker ejecuta el probe:
--interval: Con qué frecuencia corre el check (por defecto 30s). Acórtalo solo en servicios donde los segundos importan.--timeout: Cuánto puede tardar un check antes de contar como fallido (por defecto 30s).--retries: Cuántos fallos seguidos pasan el contenedor a unhealthy (por defecto 3).--start-period: Ventana de arranque donde los fallos aún no cuentan (por defecto 0s).--start-interval: Intervalo entre verificaciones durante el período de arranque (por defecto 5s, requiere Docker 25.0+). Permite que una app de arranque rápido llegue antes ahealthyen lugar de esperar un--intervalcompleto por probe.
El probe corre dentro del propio contenedor: salir con 0 lo marca sano, salir con 1 lo marca unhealthy. Cualquier otro código de salida también cuenta como fallo, así que || exit 1 protege contra comandos que devuelven 2 o mueren por una señal.
Estados de salud
- starting: La ventana de arranque mientras corre
start-period— los fallos durante ella se ignoran. - healthy: La última verificación salió con 0.
- unhealthy: El check falló
retriesveces seguidas una vez terminado el período de arranque.
Qué hace “unhealthy” realmente
En Docker normal, unhealthy es solo una marca. docker ps la muestra y docker inspect expone los últimos resultados del probe bajo .State.Health — pero nada se reinicia por sí solo. restart: always reacciona a que el contenedor termine, no a su estado de salud. El reemplazo automático viene de Docker Swarm (que reprograma tareas unhealthy), de los probes de Kubernetes o de un watcher como willfarrell/autoheal que reinicia contenedores unhealthy por ti. Consulta la referencia de HEALTHCHECK del Dockerfile para la lista completa de opciones.
depends_on y service_healthy
En Compose, depends_on con condition: service_healthy retiene el arranque de un servicio hasta que la dependencia pase su health check — la solución estándar para “la API falló porque Postgres aún no estaba listo”. Ojo: es solo una barrera de arranque; si la dependencia pasa a unhealthy después, Compose no reinicia al dependiente. El ajuste de estos valores por entorno encaja bien con los archivos override de Compose, como muestran los ejemplos avanzados de abajo. Detalles en la referencia del archivo Compose.
Depurar un check atascado
Cuando un contenedor oscila entre starting y unhealthy, mira los últimos resultados del probe antes de tocar nada:
docker inspect --format='{{json .State.Health}}' <nombre-contenedor> | jq
La salida muestra las últimas cinco verificaciones con código de salida, stdout y stderr — la causa clásica es que falta curl o wget en la imagen, lo que falla con código 127 antes de que tu app siquiera se pruebe.
Variantes
Cada método de probe cambia tamaño de imagen por flexibilidad. Elige el más simple que funcione con lo que ya tienes instalado:
| Método de Check | Requisito de Imagen | Usar Cuando |
|---|---|---|
| curl -f | curl instalado | Check HTTP estándar |
| wget —spider | wget instalado | Alpine sin curl |
| Script propio | bash + herramientas | Checks de varios pasos |
| pg_isready | Imagen PostgreSQL | Readiness de base de datos |
| redis-cli ping | Imagen Redis | Readiness de caché |
| node -e | Imagen Node.js | Check basado en JS |
Para servicios HTTP, prefiere curl o wget sobre un script propio — menos piezas que se mueven. Usa un script solo cuando la verificación de verdad tenga varios pasos.
Ejemplos Avanzados
La configuración de arriba cubre los casos de todos los días. Estas variantes manejan las situaciones que aparecen cuando el check ya corre en producción: runtimes compilados, verificaciones de varias señales, logging de auditoría, ajuste por entorno y servicios sin listener HTTP. Todos los archivos de esta página están también en el repo companion, listos para ejecutar.
Endpoint de Health en Java (Spring Boot)
// src/main/java/com/example/HealthController.java
package com.example;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.boot.actuate.health.Health;
import org.springframework.boot.actuate.health.HealthIndicator;
import org.springframework.stereotype.Component;
@RestController
public class HealthController {
@GetMapping("/health")
public String health() {
return "{\"status\":\"healthy\"}";
}
}
@Component
public class DatabaseHealthIndicator implements HealthIndicator {
@Override
public Health health() {
// Verificar conectividad a base de datos
try {
// Ejecutar query simple
return Health.up().withDetail("database", "reachable").build();
} catch (Exception e) {
return Health.down().withDetail("error", e.getMessage()).build();
}
}
}
# application.yml — Habilitar endpoints de health de actuator
management:
endpoints:
web:
exposure:
include: health,info
endpoint:
health:
show-details: when_authorized
Para indicadores personalizados que se conectan a estos health groups — consultas de base de datos, pings de Redis, probes de APIs externas — mira Health Checks Personalizados con Spring Boot Actuator.
Script de Health Check de Varios Pasos
#!/bin/bash
# healthcheck-advanced.sh — Verificación de salud en varios pasos
set -e
FAIL=0
# Paso 1: Verificar endpoint HTTP
HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" http://localhost:8000/health 2>/dev/null || echo "000")
if [ "$HTTP_CODE" != "200" ]; then
echo "FAIL: Endpoint HTTP devolvió $HTTP_CODE"
FAIL=1
fi
# Paso 2: Verificar espacio en disco
DISK_USAGE=$(df / | awk 'NR==2 {print int($5)}')
if [ "$DISK_USAGE" -gt 90 ]; then
echo "FAIL: Uso de disco al ${DISK_USAGE}%"
FAIL=1
fi
# Paso 3: Verificar si el proceso crítico está corriendo
if ! pgrep -x "gunicorn" > /dev/null; then
echo "FAIL: proceso gunicorn no encontrado"
FAIL=1
fi
# Paso 4: Verificar uso de memoria
MEM_USAGE=$(free | awk '/Mem:/ {printf "%.0f", $3/$2 * 100}')
if [ "$MEM_USAGE" -gt 95 ]; then
echo "FAIL: Uso de memoria al ${MEM_USAGE}%"
FAIL=1
fi
if [ "$FAIL" -eq 0 ]; then
exit 0
else
exit 1
fi
Health Check con Logging
#!/bin/bash
# healthcheck-logged.sh — Health check con log de auditoría
LOG_FILE="/var/log/healthcheck.log"
TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" http://localhost:3000/health 2>/dev/null || echo "000")
if [ "$HTTP_CODE" = "200" ]; then
echo "$TIMESTAMP OK HTTP=$HTTP_CODE" >> "$LOG_FILE"
exit 0
else
echo "$TIMESTAMP FAIL HTTP=$HTTP_CODE" >> "$LOG_FILE"
exit 1
fi
Override de Docker Compose para Ajuste de Health Check
# docker-compose.prod.yml — Override de health check para producción
services:
api:
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
interval: 15s
timeout: 3s
retries: 5
start_period: 30s
db:
healthcheck:
test: ["CMD-SHELL", "pg_isready -U postgres -d mydb && psql -U postgres -d mydb -c 'SELECT 1'"]
interval: 10s
timeout: 5s
retries: 10
start_period: 60s
# Aplicar overrides de health check de producción
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d
Health Check para Worker de Cola de Mensajes
Un worker sin servidor HTTP no puede responder a una petición de probe, así que el truco habitual es un archivo de heartbeat que el worker toca en cada iteración del bucle. El health check entonces mide la edad del archivo en lugar de golpear un endpoint:
FROM node:20-alpine
WORKDIR /app
COPY . .
RUN npm ci --omit=dev
# Health check para un worker que procesa mensajes de una cola
HEALTHCHECK --interval=60s --timeout=10s --retries=3 --start-period=30s \
CMD node -e " \
const fs = require('fs'); \
const stats = fs.statSync('/tmp/worker.heartbeat'); \
const age = (Date.now() - stats.mtimeMs) / 1000; \
if (age > 120) { console.error('Heartbeat stale: ' + age + 's'); process.exit(1); } \
console.log('Heartbeat OK: ' + age + 's'); \
"
CMD ["node", "worker.js"]
// worker.js — Escribir archivo de heartbeat periódicamente
const fs = require("fs");
setInterval(() => {
fs.writeFileSync("/tmp/worker.heartbeat", new Date().toISOString());
}, 30000);
Rendimiento
- Mantén los comandos de health check rápidos. Apunta a menos de 1 segundo de ejecución:
# Rápido: check HTTP simple
curl -sf -m 2 http://localhost:3000/health
# Lento: query a base de datos
psql -c "SELECT count(*) FROM large_table" # No hacer esto
- Usa
--start-periodpara evitar falsos negativos durante el arranque. Ajústalo al tiempo típico de arranque de tu app más un 50 por ciento de margen:
# La app tarda ~20s en arrancar, ajustar start-period a 30s
HEALTHCHECK --start-period=30s --interval=30s --timeout=5s --retries=3 \
CMD curl -f http://localhost:3000/health
- Evita health checks que escriben a disco. Cada check corre con frecuencia y puede llenar el disco de logs:
# Mal: escribe a disco cada 30s
HEALTHCHECK CMD curl -f http://localhost:3000/health >> /var/log/health.log
# Bien: sin escrituras a disco
HEALTHCHECK CMD curl -sf http://localhost:3000/health
Mejores Prácticas
- Añade siempre un
HEALTHCHECKa los Dockerfiles de producción — sin él, “en ejecución” es todo lo que Docker puede prometer. - Ajusta
--start-periodal tiempo real de arranque de tu app más margen (10-30s cubre la mayoría; las apps JVM pueden necesitar 60s o más). - Usa
--interval=30spara servicios generales y10ssolo en infraestructura donde los segundos importan. Cada intervalo es una petición contra tu app. - Mantén
--timeoutcorto (3-10s). Un probe que se cuelga es peor que ninguno — nunca devuelve la señal de fallo para la que lo configuraste. - Crea un endpoint
/healthdedicado que devuelva 200 sin efectos secundarios: sin queries a la base de datos, sin escrituras en caché, sin verificación de auth. - Sondea la app en sí, no solo el puerto — un socket que escucha sigue aceptando conexiones mientras el event loop está atascado.
- Usa
depends_onconcondition: service_healthyen Compose para ordenar el arranque. - Para bases de datos, usa las herramientas integradas (
pg_isready,redis-cli ping) en lugar de HTTP — ya están en la imagen y conocen el protocolo.
Errores Comunes
- No ajustar
--start-period. Las apps de arranque lento se marcan unhealthy antes de terminar de iniciar — el problema clásico de JVM y Rails. - Apuntar el health check a la base de datos. Añade carga en cada intervalo y puede causar fallos en cascada cuando la DB tiene un tropiezo.
- Poner
--intervalmuy bajo (1-5s). Gasta CPU y puede sobrecargar la app con peticiones de salud. - No crear un endpoint de salud dedicado. Verificar
/puede devolver 200 aunque la API esté rota — las páginas de inicio suelen funcionar mientras la lógica de negocio no. - Olvidar instalar curl o wget en la imagen. El probe muere con código 127 y el contenedor pasa a unhealthy por un binario que falta, no por nada que haya hecho tu app.
- Asumir que Docker reinicia contenedores unhealthy.
docker runnormal no lo hace — necesitas Swarm, probes de Kubernetes o un watcher como autoheal para eso. - Esperar que Kubernetes ejecute
HEALTHCHECK. No lo hace; define probes de liveness y readiness en el pod spec en su lugar. - No usar
depends_onconcondition: service_healthy. Los contenedores arrancan antes de que las dependencias estén listas.
Preguntas frecuentes
¿Qué pasa cuando un contenedor se marca unhealthy?
En Docker normal, nada automático — docker ps muestra (unhealthy) y el estado se puede consultar con docker inspect, eso es todo. Docker Swarm reemplaza las tareas unhealthy por unas nuevas. Kubernetes nunca ve la marca: ignora HEALTHCHECK y aplica sus propios probes de liveness/readiness desde el pod spec.
¿Debo usar el mismo endpoint para liveness y readiness?
No. Liveness verifica si la app está viva (debe ser barato, sin dependencias). Readiness verifica si la app puede servir peticiones (puede revisar conectividad a base de datos). Usa /health para liveness y /ready para readiness — mezclarlos causa reinicios cuando el problema real es una dependencia saturada.
¿Puedo deshabilitar un health check de la imagen base?
Sí. Usa HEALTHCHECK NONE en tu Dockerfile para deshabilitar health checks heredados.
¿Cómo verifico la salud del contenedor desde la CLI?
docker inspect --format='{{.State.Health.Status}}' <nombre-contenedor>
Esto devuelve healthy, unhealthy o starting.
¿Por qué mi contenedor se queda en "starting"?
O el start-period aún no terminó, o el probe muere antes de que tu app siquiera se pruebe. Ejecuta docker inspect --format='{{json .State.Health}}' <contenedor> y lee la salida del probe — el sospechoso habitual es que falte curl o wget (código 127), seguido de que la app escuche en un puerto distinto al que golpea el check.
¿Cuál es la diferencia entre HEALTHCHECK y una política de reinicio?
HEALTHCHECK reporta si la app de dentro funciona. Una política restart reacciona a que el contenedor termine — no dice nada de una app viva pero colgada. Se complementan: la política de reinicio cubre las caídas, el health check saca a la superficie el estado zombie, y algo externo (Swarm, probes de K8s, autoheal) actúa sobre él.
Recursos Relacionados
Endpoint de Health Check
Cómo implementar un endpoint de health check listo para producción para monitoreo y load balancers.
PatternPatrón Health Check: Sondeos de Liveness y Readiness
Implementa sondeos de liveness y readiness para orquestadores. Cubre probes en Kubernetes, chequeos de dependencias y degradación elegante.
RecipeOptimización de Multi-Stage Builds en Docker
Reduce el tamaño de imagen y el tiempo de build con multi-stage builds, orden de capas inteligente, cache mounts de BuildKit y un .dockerignore ajustado.
RecipeSobrescribe la Configuración de Docker Compose por Entorno
Cómo usar archivos override de Docker Compose para configuraciones por entorno: desarrollo, test, staging y producción, con profiles y secrets.
RecipeAislamiento de Red Docker y Seguridad Entre Contenedores
Asegura la comunicación entre contenedores con redes Docker personalizadas, segmentación de red y políticas de control de acceso.
DocPlantilla de Checklist de Despliegue
Una checklist de verificación lista para copiar que asegura despliegues de producción seguros, desde los tests previos hasta el monitoreo posterior.