Health Check
A health check is the mechanism that periodically verifies whether the application inside a container is actually functioning. Docker can tell whether the main process is still alive, but that is not the same as knowing whether the app can still serve real traffic.
βΆArchitecture Diagram
π ProcessDashed line animations indicate the flow direction of data or requests
A process can keep running while the application is effectively broken: deadlocked, disconnected from its database, or stuck returning only errors. If teams only track process existence, they miss that half-dead state. Orchestrated systems need a stronger signal before they decide on restart or traffic routing.
Manual container operations once relied on logs and human inspection. That broke down as teams started operating larger fleets. Health signals became necessary so systems could automate restart decisions, startup order, and traffic handling instead of leaving all judgment to people.
Health checks move through three states. A container begins as `starting`, and failures during the configured start period do not yet mark it unhealthy. After that, Docker runs the configured probe command at each interval. Exit code 0 marks the container healthy. Repeated failures up to the retry limit eventually mark it unhealthy.
The HEALTHCHECK instruction
HEALTHCHECK --interval=30s --timeout=3s --start-period=10s --retries=3 \
CMD curl -f http://localhost:8080/health || exit 1Docker runs the command at the given interval. Exit code 0 marks success. Repeated failures beyond the retry threshold turn the container unhealthy. `start-period` gives the app time to warm up.
Using readiness in Compose dependencies
services:
db:
image: postgres:16
healthcheck:
test: ["CMD-SHELL", "pg_isready -U postgres"]
interval: 10s
retries: 5
api:
depends_on:
db:
condition: service_healthyThe API service waits until the database is healthy. Plain `depends_on` only handles order, while `condition: service_healthy` waits for real readiness.
Docker HEALTHCHECK and Kubernetes probes both evaluate actual application state, but Docker offers a simpler healthy versus unhealthy model. Kubernetes splits the question into liveness, readiness, and startup probes. For single-container or Compose-based environments, Docker HEALTHCHECK is often sufficient. Larger orchestration systems typically need the more fine-grained model.
The most important design choice is what to probe. A simple open port check is weaker than a real application endpoint that verifies key dependencies. At the same time, the check must stay lightweight enough not to become its own source of load. Timing values such as start period and retries should match the application's real startup profile, or healthy services can be marked unhealthy too early while real failures are detected too slowly.