StackPractices
beginner Por Mathias Paulenko

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.

Temas: devops

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 ps muestre 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_healthy para 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 a healthy en lugar de esperar un --interval completo 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ó retries veces seguidas una vez terminado el período de arranque.
stateDiagram-v2 diagram: [*

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 CheckRequisito de ImagenUsar Cuando
curl -fcurl instaladoCheck HTTP estándar
wget —spiderwget instaladoAlpine sin curl
Script propiobash + herramientasChecks de varios pasos
pg_isreadyImagen PostgreSQLReadiness de base de datos
redis-cli pingImagen RedisReadiness de caché
node -eImagen Node.jsCheck 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

  1. 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
  1. Usa --start-period para 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
  1. 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 HEALTHCHECK a los Dockerfiles de producción — sin él, “en ejecución” es todo lo que Docker puede prometer.
  • Ajusta --start-period al 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=30s para servicios generales y 10s solo en infraestructura donde los segundos importan. Cada intervalo es una petición contra tu app.
  • Mantén --timeout corto (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 /health dedicado 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_on con condition: service_healthy en 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 --interval muy 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 run normal 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_on con condition: 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.