Verificación de salud en contenedores Docker

Qué abarca este artículo sobre verificación de salud en Docker

• Qué es una verificación de salud.
• Cómo definir verificaciones de salud en Dockerfiles y Compose.
• Cómo responde Docker ante fallos.
• Ejemplos prácticos para servicios web, bases de datos y Ollama.
• Consejos y errores comunes.

Introducción: Verificación de salud en contenedores Docker

Un contenedor Docker puede estar en ejecución sin que la aplicación en su interior esté realmente lista o funcionando correctamente. Las verificaciones de salud permiten comprobar periódicamente el estado de una aplicación. Docker marca entonces el contenedor como healthy o unhealthy y puede reiniciarlo automáticamente o generar alertas cuando sea necesario.

Este artículo muestra cómo funcionan las verificaciones de salud y cómo configurarlas para servicios de IA típicos como Ollama, Open WebUI o bases de datos.

Conceptos clave

• Healthcheck: Verificación periódica del estado de salud de la aplicación.
• Interval: Tiempo entre dos verificaciones.
• Timeout: Tiempo máximo de espera para obtener el resultado de la verificación.
• Start Period: Tiempo durante el cual se ignoran los fallos para permitir el arranque.
• Retries: Número de intentos fallidos permitidos antes de que el contenedor sea marcado como unhealthy.
• Restart Policy: Comportamiento al reiniciar.
• Exit Code: Valor devuelto por el comando de verificación. 0 significa saludable, 1 significa no saludable.

Por qué son importantes las verificaciones de salud

• Los contenedores se marcan como listos solo cuando la aplicación se ejecuta.
• Los errores se detectan temprano.
• Los proxies inversos y equilibradores de carga pueden preferir contenedores saludables.
• Los reinicios automáticos aumentan la disponibilidad.
• El monitoreo puede reaccionar al estado de salud.

Verificación de salud en Dockerfile

FROM nginx:latest

HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
  CMD curl -f http://localhost/ || exit 1

Esta verificación comprueba cada 30 segundos si el servidor web local responde.

Verificación de salud en Docker Compose

services:
  web:
    image: nginx
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost/"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 10s
    restart: unless-stopped

Consultar el estado

docker ps

La columna STATUS muestra (healthy) o (unhealthy).

Para más detalle:

docker inspect --format='{{.State.Health.Status}}' containername

Ejemplo: Ollama

services:
  ollama:
    image: ollama/ollama
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:11434/"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 30s
    volumes:
      - ollama-data:/root/.ollama
    restart: unless-stopped

Esta verificación comprueba si la API de Ollama es accesible.

Ejemplo: Open WebUI

services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 60s
    restart: unless-stopped

Ejemplo: PostgreSQL

services:
  postgres:
    image: postgres:16
    environment:
      POSTGRES_USER: user
      POSTGRES_PASSWORD: pass
      POSTGRES_DB: appdb
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U user -d appdb"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 20s
    restart: unless-stopped

Verificaciones más complejas

A veces una simple verificación de estado HTTP no es suficiente. Puedes usar scripts propios que verifiquen si funciones críticas están operativas:

#!/bin/sh
if curl -f http://localhost/api/health | grep -q '"ok":true'; then
  exit 0
else
  exit 1
fi

Coloca el script en el contenedor e invócalo como verificación de salud.

Políticas de reinicio

Política	Comportamiento
no	Nunca reiniciar.
on-failure	Solo en caso de código de error.
always	Reiniciar siempre.
unless-stopped	Reiniciar a menos que se detenga manualmente.

Combinación recomendada:

restart: unless-stopped

Desactivar la verificación de salud

Si una imagen preconfigurada tiene una verificación de salud inapropiada, puedes sobrescribirla:

services:
  app:
    image: irgendein-image
    healthcheck:
      disable: true

Consejos

• La verificación de salud debe comprobar un endpoint significativo, no solo el proceso.
• Elige la duración de inicio de forma generosa.
• No establezcas el intervalo demasiado corto para conservar recursos.
• Ajusta el timeout al tiempo de respuesta real.
• Monitorea los logs de las verificaciones de salud.
• Mantén los scripts de verificación de salud personalizados breves.

Errores comunes

• Intervalo demasiado estricto: Alta carga por verificaciones constantes.
• Duración de inicio demasiado corta: El contenedor se marca como no saludable durante el arranque.
• Protocolo incorrecto: Verificar HTTPS cuando se ejecuta HTTP.
• Herramientas faltantes en la imagen: curl no está disponible, el script falla.
• Solo verificar el proceso: La aplicación está bloqueada, pero el proceso sigue ejecutándose.
• Sin política de reinicio: Los contenedores no saludables continúan funcionando.
• Salidas de verificación en logs: Entradas de log confusas.

Enlaces y recursos adicionales

• BotServ.de Docker Monitoring
• BotServ.de Docker Logs
• BotServ.de Docker Security
• BotServ.de Docker Compose

FAQ: Verificación de salud en Docker

¿Necesita cada contenedor una verificación de salud? No, pero se recomienda para servicios importantes.

¿Con qué frecuencia se ejecuta una verificación de salud? Por defecto cada 30 segundos, pero es configurable.

¿Qué sucede cuando el estado es unhealthy? Docker muestra el estado. Con una política de reinicio, el contenedor puede reiniciarse.

¿Puedo usar comandos personalizados? Sí, se permiten verificaciones arbitrarias en shell o CMD.

¿Son las verificaciones de salud lo mismo que Readiness Probes en Kubernetes? Similar, pero Kubernetes también ofrece Readiness y Startup Probes adicionales.

Fuentes y lecturas complementarias

• Docker Healthcheck: https://docs.docker.com/engine/reference/builder/#healthcheck
• Docker Restart Policy: https://docs.docker.com/config/containers/start-containers-automatically/
• Compose Healthcheck: https://docs.docker.com/compose/compose-file/compose-file-v3/#healthcheck

Resumen: Verificación de salud en contenedores Docker

Las verificaciones de salud son una forma sencilla de monitorear la disponibilidad real de los contenedores Docker. Se pueden definir en el Dockerfile o en Docker Compose y funcionan estrechamente con las políticas de reinicio. Para servicios de IA importantes como Ollama, Open WebUI o bases de datos, conviene configurar verificaciones específicas de endpoints. Lo fundamental es elegir intervalos sensatos, permitir tiempos de inicio suficientes y usar métodos de verificación precisos. Quién implementa verificaciones de salud desde el principio mejora notablemente la estabilidad de todo el stack.