Instrucción HEALTHCHECK Dockerfile: guía práctica

La instrucción HEALTHCHECK Dockerfile sirve para que Docker pueda comprobar si un contenedor sigue funcionando correctamente desde dentro. No se limita a saber si el proceso principal está vivo: permite ejecutar una prueba real, por ejemplo consultar un endpoint HTTP, comprobar un puerto o validar que un servicio responde.

Sin un healthcheck, un contenedor puede aparecer como levantado aunque la aplicación esté bloqueada, no acepte conexiones o haya fallado una dependencia interna. Con una comprobación bien diseñada, Docker marca el contenedor como healthy o unhealthy y te da una señal mucho más útil para depurar.

En esta lección vas a aprender cómo funciona la instrucción HEALTHCHECK Dockerfile, qué opciones tiene, cómo inspeccionar el resultado y qué errores evitar para no crear comprobaciones lentas, frágiles o demasiado agresivas.

👉 Y recuerda, si quieres aprender más de Linux, pincha en este curso de Linux gratis.

🐳 Si quieres aprender más de Docker, pincha en este curso de Docker gratis.

Qué hace HEALTHCHECK en Dockerfile

HEALTHCHECK añade una prueba periódica a la imagen. Cuando un contenedor arranca desde esa imagen, Docker ejecuta el comando configurado y registra el estado de salud del contenedor. Si el comando devuelve código 0, la comprobación se considera correcta. Si devuelve código 1, se considera fallida.

Esto no reinicia automáticamente el contenedor por sí solo en Docker clásico. Lo que hace es exponer un estado de salud que puedes consultar con docker ps, docker inspect o herramientas externas. En Compose, Swarm u otros sistemas, esa señal puede integrarse con políticas y dependencias, pero conviene entender primero la base.

docker ps
docker inspect --format="{{json .State.Health}}" nombre_contenedor

docker ps
docker inspect --format="{{json .State.Health}}" nombre_contenedor

El primer comando muestra una vista rápida del estado. El segundo permite inspeccionar el bloque de salud del contenedor, incluyendo el estado actual, intentos y registros recientes de la comprobación.

Sintaxis de la instrucción HEALTHCHECK Dockerfile

La forma más habitual de usar la instrucción HEALTHCHECK Dockerfile es declarar un intervalo, un timeout, un número de reintentos y el comando que decide si la aplicación está sana.

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

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

En este ejemplo, Docker espera un periodo inicial antes de evaluar fallos, ejecuta la comprobación cada treinta segundos, limita cada intento a cinco segundos y marca el contenedor como no saludable después de varios fallos consecutivos.

Opción	Para qué sirve	Ejemplo
–interval	Define cada cuánto se ejecuta la comprobación.	–interval=30s
–timeout	Tiempo máximo que puede tardar cada intento.	–timeout=5s
–start-period	Margen inicial para que la aplicación arranque sin contar fallos.	–start-period=20s
–start-interval	Intervalo usado durante el periodo inicial en versiones modernas de Docker.	–start-interval=5s
–retries	Fallos consecutivos necesarios para marcar unhealthy.	–retries=3
CMD	Comando que decide si el contenedor está sano.	CMD curl -f http://localhost:8080/health \|\| exit 1

La clave es que el comando sea rápido, local y representativo. Un healthcheck no debería depender de servicios externos que puedan fallar por red, DNS o latencia ajena a la aplicación.

Ejemplo práctico con una aplicación web

Supón que tienes una aplicación que expone un endpoint de salud en la ruta /health. El Dockerfile puede instalar la herramienta necesaria y usarla para comprobar la aplicación desde dentro del contenedor.

FROM nginx:stable

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

FROM nginx:stable

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

Este ejemplo usa Nginx y comprueba la página local. En una aplicación real, lo ideal es consultar un endpoint específico de salud que verifique lo mínimo necesario: que el proceso responde y que la aplicación está lista para atender tráfico.

docker build -t demo-healthcheck:1.0 .
docker run -d --name demo-health demo-healthcheck:1.0
docker ps
docker inspect --format="{{.State.Health.Status}}" demo-health

docker build -t demo-healthcheck:1.0 .
docker run -d --name demo-health demo-healthcheck:1.0
docker ps
docker inspect --format="{{.State.Health.Status}}" demo-health

Después de arrancar el contenedor, Docker tardará un poco en evaluar la comprobación. El estado puede pasar por starting, healthy o unhealthy según el resultado del comando configurado.

HEALTHCHECK en Docker Compose

También puedes definir healthchecks directamente en Docker Compose. Esto es útil cuando no controlas la imagen base o cuando quieres ajustar la comprobación por entorno sin modificar el Dockerfile.

services:
  web:
    image: nginx:stable
    ports:
      - "8080:80"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost/"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 20s

services:
  web:
    image: nginx:stable
    ports:
      - "8080:80"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost/"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 20s

Este bloque declara una comprobación equivalente en Compose. Recuerda que el comando se ejecuta dentro del contenedor, así que las herramientas usadas por el healthcheck deben existir dentro de la imagen. Si curl no está instalado, la comprobación fallará aunque la aplicación esté bien.

Un punto importante: depends_on puede esperar condiciones en algunos escenarios de Compose, pero no sustituye un diseño correcto de arranque. La aplicación también debe manejar reintentos si una base de datos o servicio interno tarda en estar listo.

Cómo interpretar healthy y unhealthy

El estado healthy significa que el último conjunto de comprobaciones pasó correctamente. Unhealthy significa que Docker detectó fallos consecutivos según la configuración de retries. Esto ayuda a localizar problemas, pero no explica por sí solo la causa exacta.

docker inspect --format="{{json .State.Health.Log}}" demo-health
docker logs demo-health

docker inspect --format="{{json .State.Health.Log}}" demo-health
docker logs demo-health

Combina el estado de salud con los logs de la aplicación. Si el healthcheck falla, revisa si el endpoint existe, si la aplicación tarda más de lo esperado en arrancar, si el comando está disponible dentro de la imagen y si el timeout es demasiado corto.

La instrucción HEALTHCHECK Dockerfile debe medir algo útil, no solo ejecutar un comando que siempre devuelve éxito. Si la comprobación no representa el estado real de la aplicación, puede darte una falsa sensación de seguridad.

Errores comunes con HEALTHCHECK

Usar herramientas que no existen en la imagen: si defines curl, wget o nc, asegúrate de que están instalados o usa una alternativa disponible.
Comprobar servicios externos: un healthcheck debería medir la salud local del contenedor, no la disponibilidad de Internet o de un proveedor externo.
Timeout demasiado bajo: puede marcar unhealthy una aplicación que simplemente tarda unos segundos más en responder.
Intervalos demasiado agresivos: una comprobación pesada cada pocos segundos añade carga innecesaria.
Confundir healthcheck con reinicio automático: el estado unhealthy no implica por sí solo que Docker reinicie el contenedor en todos los modos de ejecución.
Usar endpoints profundos: si la comprobación depende de demasiadas capas, será más difícil distinguir el problema real.

El error más frecuente es tratar el healthcheck como una prueba completa de negocio. Normalmente debe ser una señal simple y barata: la aplicación está levantada, responde y puede aceptar tráfico básico.

Buenas prácticas para la instrucción HEALTHCHECK Dockerfile

Diseña comprobaciones pequeñas, rápidas y estables. Un buen healthcheck no debería modificar datos, crear sesiones ni ejecutar tareas costosas. Solo debe observar si el servicio está listo para trabajar.

Usa start-period cuando la aplicación tarda en arrancar. Esto evita marcar fallos durante una fase normal de inicialización, por ejemplo al cargar cachés, migrar datos o iniciar un servidor web pesado.

Documenta qué significa healthy en tu proyecto. No es lo mismo comprobar que el proceso escucha en un puerto que comprobar una ruta de salud que valida dependencias internas. Cuanto más claro esté el criterio, más fácil será depurar una incidencia.

En resumen, la instrucción HEALTHCHECK Dockerfile es una herramienta muy útil para detectar contenedores vivos pero no saludables. Bien usada, mejora el diagnóstico; mal usada, puede añadir ruido y falsos positivos.

Lecciones relacionadas del curso Docker

Documentación oficial y recursos

Con esta base, puedes añadir healthchecks útiles sin convertirlos en una fuente de falsos errores. Empieza con una comprobación simple, valida el estado con docker inspect y ajusta intervalos, timeout y reintentos según el comportamiento real de tu aplicación.