Docker health checks: cómo saber si tu servicio está vivo

Cuando despliegas servicios en Docker, un docker ps te dirá si el contenedor está en marcha. Pero que un contenedor esté corriendo no significa que el servicio dentro funcione correctamente. Un servidor web puede estar escuchando, pero su base de datos estar caída o sus dependencias externas inaccesibles. Aquí es donde los Docker health checks se vuelven críticos, ya que te permiten verificar la salud real de tu aplicación.

Un healthcheck es una instrucción que Docker ejecuta periódicamente dentro del contenedor para determinar si el servicio está operativo. Esto va más allá de un simple chequeo de puerto, evaluando la lógica interna de tu aplicación.

Por qué necesitas health checks más allá de un docker ps

Imagina un backend NodeJS que arranca sin problemas, pero no puede conectar con la base de datos. El contenedor seguirá en estado Up, pero tu API devolverá errores 500 a los usuarios. Sin esta verificación, tus herramientas de monitorización externas solo verán que el puerto 80 (o el que uses) responde, sin saber que el servicio real es inútil.

Mi regla es simple: si un servicio es crítico para la operación, debe tener una comprobación de salud bien definida. Esta es una de las primeras cosas que implemento en entornos de producción, ya que evita sorpresas desagradables y permite una reacción rápida ante fallos silenciosos. Para entender mejor cómo la monitorización impacta la fiabilidad, puedes revisar conceptos básicos de monitorización VPS.

Cómo implementar un Docker health check básico

Las comprobaciones de salud se definen en el Dockerfile o en el docker-compose.yml. La forma más común es usar un comando que devuelva un código de salida: 0 para éxito, 1 para fallo. Docker ejecutará este comando y, basándose en el resultado, marcará el contenedor como healthy o unhealthy.

Un ejemplo para un servidor web que escucha en el puerto 8080 y expone un endpoint de salud en /health:

# Dockerfile
HEALTHCHECK --interval=30s --timeout=10s --retries=3 \
  CMD curl --fail http://localhost:8080/health || exit 1

En este caso, Docker intentará cada 30 segundos (--interval) hacer una petición a /health. Si no responde en 10 segundos (--timeout), lo considera un fallo. Si falla 3 veces seguidas (--retries), el contenedor se marca como unhealthy.

Para un servicio en docker-compose.yml, la sintaxis es similar y a menudo más conveniente:

# docker-compose.yml
version: '3.8'
services:
  webapp:
    image: myapp:latest
    ports:
      - "80:8080"
    healthcheck:
      test: ["CMD", "curl", "--fail", "http://localhost:8080/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 20s # Opcional: tiempo para que la app arranque antes del primer check

El start_period es útil para aplicaciones que tardan en arrancar y pasar sus propias comprobaciones internas. Durante ese periodo, el contenedor está en estado starting, no unhealthy, aunque la verificación de salud falle. Esto evita que Docker reinicie un contenedor que solo está inicializándose.

Ventajas y desventajas de los health checks

Implementar estas verificaciones parece sencillo, pero como toda herramienta, tiene sus implicaciones prácticas.

Lo que ganas:

• Detección temprana de fallos lógicos: Identificas problemas que un simple check de conectividad de red no vería.
• Automatización de reinicios: Docker puede configurarse para reiniciar contenedores unhealthy automáticamente, mejorando la resiliencia del servicio. Para estrategias de despliegue más robustas, considera cómo los deploys automáticos con webhooks y Docker pueden complementarse con estas verificaciones.
• Integración con orquestadores: Herramientas como Kubernetes usan estos estados para gestionar despliegues, realizar actualizaciones progresivas y decidir dónde rutear el tráfico.
• Monitorización precisa: Tus herramientas externas de monitorización pueden leer el estado de salud de Docker para darte una imagen precisa y real del estado de tus servicios.

Lo que complicas:

• Falsos positivos: Una comprobación de salud mal diseñada puede marcar un servicio como unhealthy cuando realmente funciona bien, provocando reinicios innecesarios o alertas falsas.
• Carga extra: Cada ejecución de la verificación consume recursos del contenedor. Un intervalo muy bajo o un comando complejo pueden impactar el rendimiento del servicio principal.
• Diseño del endpoint: Necesitas un endpoint /health en tu aplicación que refleje la salud real, no solo un “hola mundo”. Debe chequear bases de datos, servicios externos y otros componentes críticos.

Diseñar una comprobación de salud útil y fiable es el mayor reto. No sirve de nada si solo comprueba que el servidor web está respondiendo; debe validar las dependencias críticas para que el servicio sea funcional.

Qué comprobar en un health check robusto

Una verificación de salud no debería ser un simple echo "OK" o una petición a la raíz de tu aplicación. Debería simular una operación crítica o al menos verificar las dependencias clave para considerar que el servicio está verdaderamente “vivo” y funcional.

Considera incluir esto en tu endpoint /health o en tu script de verificación de salud:

1. Conectividad a base de datos: Intenta una consulta básica que no modifique datos, solo para verificar la conexión.
2. Conectividad a servicios externos: Si tu aplicación depende de una API de terceros o de otro microservicio, intenta un ping o una consulta ligera.
3. Estado de la caché: Si usas Redis o Memcached, verifica su accesibilidad y si puedes leer/escribir datos básicos.
4. Espacio en disco: Si tu servicio escribe archivos o logs, comprueba que hay espacio disponible en el volumen.

Estas comprobaciones son una parte fundamental de la infraestructura moderna basada en contenedores. Aseguran que tus despliegues sean más robustos y te dan la tranquilidad de que tus servicios funcionan como esperas. Si quieres ir más allá en la monitorización de tus contenedores, te recomiendo leer sobre cómo integrar cAdvisor y Prometheus para una monitorización avanzada de Docker. A veces, un contenedor se marca como unhealthy porque ni siquiera arranca correctamente; en esos casos, saber cómo depurar un contenedor Docker que no arranca es esencial. Si quieres implementar alertas cuando tus servicios caen, puedes configurar alertas de Telegram para tu servidor y recibir notificaciones al instante.