How does the Dockerfile HEALTHCHECK instruction work, and what do its --interval, --timeout, --retries and --start-period options control?

## Mechanics The instruction has two forms: `HEALTHCHECK [OPTIONS] CMD <command>` and `HEALTHCHECK NONE`, the latter used to cancel a check inherited from a base image. The command runs *inside* the container, using the container's own filesystem and network namespace, on the daemon's schedule. Its exit status is the verdict: 0 healthy, 1 unhealthy. Status 2 is reserved and should not be used. Both shell form (`CMD curl -f http://localhost:8080/health || exit 1`) and exec form (`CMD ["curl", "-f", "http://localhost:8080/health"]`) work; exec form skips the shell. The daemon records the last few results, including exit code and truncated output, in the container state. Read them with `docker inspect --format '{{json .State.Health}}' <container>`; `docker ps` shows the status next to the container. ## The four options **--interval** (default 30s): time between the end of one check and the start of the next. Shorter means faster detection but more load; a check is a full process spawn inside the container. **--timeout** (default 30s): a check exceeding this is killed and counted as a failure. A timeout longer than the interval is a smell - detection lags and checks queue up conceptually. **--retries** (default 3): the number of *consecutive* failures needed to move from healthy to unhealthy. A single success resets the counter. Worst-case detection time is roughly interval x retries plus timeout, which is the number to quote when someone asks how fast a failure is noticed. **--start-period** (default 0s): a startup grace window measured from container start. Failures during it do not increment the retry counter and cannot mark the container unhealthy; the status stays `starting`. The first success ends the window immediately. This exists for apps with slow boots - JVM warmups, migrations - so they are not declared dead before they ever came up. Modern engines also support **--start-interval**, a shorter interval used only during the start period, so a fast-starting container is marked healthy quickly while still tolerating a long worst case. ## Who acts on the result This is where candidates go wrong. Plain `docker run` does nothing with an unhealthy status: the container keeps running, and even `--restart` policies react to exit codes, not health. Docker Swarm reschedules unhealthy tasks. Docker Compose uses it for ordering via `depends_on: <svc>: condition: service_healthy`, which is the most common reason to add a HEALTHCHECK to an image used in local or CI stacks. Kubernetes ignores the image's HEALTHCHECK completely and relies on its own probes defined in the pod spec, so an image destined only for Kubernetes gains nothing operationally from the instruction. Load balancers and reverse proxies in front of the container use their own probes as well. ## Writing a good check Probe what proves the process can serve traffic - an in-process HTTP endpoint that does a cheap internal check. Avoid probing downstream dependencies: if the database is briefly unavailable, marking every application container unhealthy converts a dependency blip into a cascading restart storm. Keep the check cheap: it runs forever, on every container. The tool must exist in the image. Minimal and distroless images ship no curl or wget, so either add a tiny static health binary, use a language-runtime one-liner already present, or have the application expose a `--healthcheck` subcommand that dials itself. Also remember the check runs as the image's configured user, so it must have permission to run and to reach the local port. ## Practical defaults A reasonable starting point for a web service: `--interval=15s --timeout=3s --retries=3 --start-period=30s`. Detection then takes at most about 45 seconds, slow starts are tolerated, and a hung request cannot stall the checker.