Runtime Health Checks

## The problem it solves A container is "running" as long as its main process exists. That is a very weak statement about usefulness. A Java service can be alive with a deadlocked thread pool, a web server can hold its port open while every request 500s, a worker can be connected to nothing after its database credentials expire. Process liveness says "up"; users say "down". `HEALTHCHECK` closes that gap by letting the image declare an *application-level* test that the runtime executes periodically inside the container. ## Syntax In a Dockerfile: ```dockerfile HEALTHCHECK [OPTIONS] CMD <command> HEALTHCHECK NONE ``` `HEALTHCHECK NONE` disables a check inherited from a base image — useful when you build on an image that ships one you don't want. The `CMD` part follows the same two forms as everywhere else in a Dockerfile: - **shell form** — `HEALTHCHECK CMD curl -f http://localhost:8080/healthz || exit 1` runs through `/bin/sh -c`, so shell features like `||` work. - **exec form** — `HEALTHCHECK CMD ["/bin/healthcheck"]` runs the binary directly with no shell involved, which is what you need in an image that has no shell. In Compose the same thing is spelled with a `healthcheck:` block, where `test: ["CMD", ...]` is exec form and `test: ["CMD-SHELL", "..."]` is shell form. ## The exit-code contract The probe communicates only through its exit status: - **0** — the container is healthy. - **1** — the container is unhealthy. - **2** — reserved; do not use it (it does not mean anything useful and may be treated as a failure with different semantics in future). This is why so many examples end with `|| exit 1`: `curl -f` already returns non-zero on an HTTP error status, but normalising it to exactly 1 keeps the contract explicit. Anything the probe writes to stdout/stderr is captured and stored (truncated) in the health log, so a check that prints a useful reason gives you free diagnostics. ## Where the probe runs Crucially, the command runs **inside the container**, in its namespaces — so `localhost` is the container itself, and the probe can reach a port that was never published to the host. It also means the binary you call must exist in the image: `curl` is absent from many minimal bases, and distroless images have no shell at all, which is why a health check that works locally can fail with "not found" in a slimmed production image. ## Reading the result **`docker ps`** appends the health state to the status: ``` STATUS Up 2 minutes (health: starting) Up 5 minutes (healthy) Up 3 hours (unhealthy) ``` The three states are: - **starting** — no verdict yet; the container has just begun and failures are not yet being counted against it. - **healthy** — the most recent probe (or the first successful one) passed. - **unhealthy** — the probe has failed enough consecutive times to flip the verdict. **`docker inspect`** gives the detail: ``` docker inspect --format '{{json .State.Health}}' web ``` That returns `Status`, `FailingStreak` (how many consecutive failures so far), and `Log` — an array of recent probe runs, each with `Start`, `End`, `ExitCode`, and `Output`. When a container is flapping, the log is usually where the real error message is hiding. **Events**: `docker events --filter event=health_status` emits a line each time the status *changes*, which is the hook other tools use to react. ## What it does not do Two limits are worth stating up front because they surprise people: 1. **Docker Engine does not restart an unhealthy container.** Restart policies react to the main process exiting, and an unhealthy container has not exited. Something else has to act on the status. 2. **It does not affect traffic routing on plain Docker.** There is no built-in load balancer to remove the container from. Orchestration layers built on top (Swarm services, Compose's `depends_on: condition: service_healthy`) are what consume the state. So the instruction's job is to *produce a trustworthy verdict*; deciding what to do with the verdict is a separate design step.