Health Checks y Reinicio Automático

¿Por qué necesitas Health Checks?

En un entorno de producción, los containers pueden fallar por múltiples razones: errores en la aplicación, agotamiento de memoria, conexiones perdidas a bases de datos, o simplemente procesos zombies. Sin mecanismos de supervisión, un container caído permanece caído hasta que alguien lo descubre manualmente.

Los health checks resuelven este problema permitiendo que Docker interrogue periódicamente al container sobre su estado real de salud. Si el container no responde correctamente, Docker puede reiniciarlo automáticamente según la política configurada.

Configurando Health Checks

Docker proporciona la instrucción HEALTHCHECK en el Dockerfile para definir cómo verificar que un container está saludable. Esta instrucción acepta varios parámetros:

HEALTHCHECK [--interval=30s] [--timeout=10s] [--retries=3] [--start-period=40s] CMD comando

Parámetros del HEALTHCHECK

Ejemplo práctico: API REST con Node.js

FROM node:18-alpine

WORKDIR /app

COPY package*.json ./
RUN npm ci --only=production

COPY . .

EXPOSE 3000

# Health check: verifica que el endpoint /health responde correctamente
HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
  CMD node -e "
    const http = require('http');
    http.get('http://localhost:3000/health', (res) => {
      process.exit(res.statusCode === 200 ? 0 : 1);
    }).on('error', () => process.exit(1));
  "

CMD ["node", "server.js"]

Ejemplo: Base de datos PostgreSQL

FROM postgres:15-alpine

ENV POSTGRES_DB=mydb
ENV POSTGRES_USER=myuser
ENV POSTGRES_PASSWORD=mypassword

# Verificar que PostgreSQL responde a conexiones
HEALTHCHECK --interval=10s --timeout=5s --retries=5 \
  CMD pg_isready -U myuser -d mydb || exit 1

EXPOSE 5432

Políticas de Reinicio Automático

Docker ofrece múltiples políticas de reinicio que determinan qué sucede cuando un container se detiene. Estas políticas se configuran con la bandera --restart al crear el container.

Políticas disponibles

Ejemplos de uso

# Reiniciar siempre (para demonios y servicios críticos)
docker run -d --name mi-nginx --restart always -p 80:80 nginx

# Reiniciar solo en caso de fallo, máximo 5 intentos
docker run -d --name mi-app --restart on-failure:5 mi-imagen

# Reiniciar siempre excepto si se detuvo manualmente (PRODUCCIÓN)
docker run -d --name mi-api --restart unless-stopped -p 8080:8080 mi-api:latest

Combinando Health Checks y Reinicio Automático

La verdadera potencia surge cuando combinas ambas características. Cuando un health check falla consecutivamente el número de retries configurado, Docker marca el container como unhealthy. Con la política de reinicio apropiada, Docker puede automáticamente reiniciar el container para intentar recuperarlo.

Ejemplo completo: Aplicación web con base de datos

version: '3.8'

services:
  api:
    build: ./api
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s
    depends_on:
      db:
        condition: service_healthy
    ports:
      - "3000:3000"

  db:
    image: postgres:15-alpine
    restart: unless-stopped
    environment:
      POSTGRES_DB: appdb
      POSTGRES_USER: appuser
      POSTGRES_PASSWORD: secretpassword
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U appuser -d appdb"]
      interval: 10s
      timeout: 5s
      retries: 5
    
volumes:
  pgdata:

Verificando el estado de salud

# Ver estado de todos los containers incluyendo health
docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Health}}"

# Ver detalles del health check de un container específico
docker inspect --format='{{json .State.Health}}' mi-container | jq

# Ver historial de health checks
docker inspect --format='{{range .State.Health.Log}} {{.End}} - Exit: {{.ExitCode}} - Output: {{.Output}} {{end}}' mi-container

Códigos de estado del Health

Un container puede tener uno de estos estados de salud:

Casos de uso avanzados

Health check para aplicaciones con autenticación

# Verificar salud sin exponer endpoints de métricas públicos
HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:8080/api/health \
    -O /dev/null || exit 1

Health check con verificación de dependencias

#!/bin/sh
set -e

# Verificar que el servicio responde
curl -f http://localhost:8080/health || exit 1

# Verificar conexión a base de datos
nc -z db 5432 || exit 1

echo "All dependencies healthy"
exit 0

Reinicio con límite de intentos

# Detener después de 10 intentos fallidos para evitar loops infinitos
docker run -d \
  --name servicio-critico \
  --restart on-failure:10 \
  --health-cmd="pg_isready -U postgres" \
  --health-interval=30s \
  --health-retries=3 \
  mi-base-datos

Debugging de problemas

1. Verifica los logs del container: docker logs mi-container para identificar qué está causando los fallos.
2. Revisa el output del health check: docker inspect --format='{{.State.Health}}' mi-container
3. Ejecuta el comando manualmente: Entra al container y ejecuta el comando del health check para ver el error directamente.
4. Verifica recursos: Asegúrate de que el container tiene suficiente CPU y memoria asignados.
5. Revisa dependencias: Verifica que los servicios externos (bases de datos, APIs) están accesibles.

# Entrar al container y verificar manualmente
docker exec -it mi-container sh

# Dentro del container, ejecutar el health check
curl -f http://localhost:3000/health

# O verificar pg_isready si es PostgreSQL
pg_isready -U postgres

Integración con orquestación

En entornos con Docker Swarm o Kubernetes, los health checks se integran con los mecanismos de orquestación:

# En Docker Swarm, crear servicio con health check
docker service create \
  --name mi-servicio \
  --health-cmd="curl -f http://localhost:3000/health || exit 1" \
  --health-interval=30s \
  --health-retries=3 \
  --health-timeout=10s \
  --replicas=3 \
  -p 3000:3000 \
  mi-imagen:latest

"Los sistemas distribuidos tolerantes a fallos asumen que los componentes fallarán eventualmente. Diseña tus servicios asumiendo que necesitarán reiniciarse y asegura que el reinicio los lleve a un estado consistente."

Resumen de mejores prácticas

# Comando rápido para verificar todos los health checks de tus containers
docker ps --filter "health=unhealthy" --format "table {{.Names}}\t{{.Status}}"