Does the Dockerfile `HEALTHCHECK` instruction still do anything once a scheduler runs your image?

## What the instruction actually does `HEALTHCHECK` is an image-level instruction that configures the **Docker engine**, not the application. It looks like this: ``` HEALTHCHECK --interval=30s --timeout=3s --start-period=10s --retries=3 \ CMD ["/checkout", "healthcheck"] ``` When a container from that image runs, the daemon executes the command **inside the container** every `--interval`, giving it `--timeout` to finish. Exit status 0 means healthy; 1 means unhealthy. Failures during `--start-period` do not count against the container, which is how you tolerate a slow start without slackening the steady-state interval. After `--retries` consecutive failures the container's health state flips to `unhealthy`. The state is observable in three places: the `STATUS` column of `docker ps` (`Up 4 minutes (healthy)`), `docker inspect --format '{{json .State.Health}}'` — which also gives you `FailingStreak` and the last few probe outputs with their exit codes, invaluable when the check itself is broken — and the event stream, where the daemon emits `health_status: unhealthy`. **And then nothing happens.** This is the part candidates get wrong. Under plain `docker run` the engine records health and acts on it in no way at all: it will not restart the container, will not stop it, and cannot stop other containers reaching it, because the restart policy reacts to the container *exiting*, not to it being unhealthy. A container can sit `unhealthy` for a week serving errors. The instruction produces a signal for something else to consume. ## What changes at the handoff A scheduler is that something else — but it brings its own. Probes are declared in the workload spec, with the platform's own semantics for interval, timeout, failure threshold and, crucially, **action**: restart this instance, replace it, or take it out of the load-balancing set. Two consequences follow. First, the probe definition moves out of the image. Intervals and thresholds are operational settings that differ per environment — a staging deployment can afford an aggressive probe that would cause flapping in production — so they belong with the other runtime configuration, next to the resource limits and the restart behaviour. Second, the image's instruction may simply not be read. Kubernetes does not look at `HEALTHCHECK`; its probes come entirely from the pod spec. Other systems differ, and Docker's own Compose file has a `healthcheck:` key that can override or disable what the image declares. So an image whose only health story is a `HEALTHCHECK` line will be probed by nothing at all on some platforms, which is exactly the failure mode where a broken instance quietly keeps receiving traffic. ## What is still worth keeping in the image The **check command** — as opposed to the schedule around it. Whatever runs your container, something wants a cheap, dependency-light way to ask "are you serving?". Shipping that as part of the artefact means `docker run` on a laptop, a Compose file in CI, and the production spec all ask the same question the same way. That has a sharp edge on minimal images. An order-checkout API that ships as a single Go binary in a `scratch` image has no shell and no `curl`, so the familiar ``` HEALTHCHECK CMD curl -f http://localhost:8143/healthz || exit 1 ``` cannot work: shell form wraps the command in `/bin/sh -c`, and there is no `/bin/sh`. The fix is to make the binary check itself and use exec form: ``` HEALTHCHECK --interval=20s --timeout=2s --start-period=5s --retries=3 \ CMD ["/checkout", "healthcheck"] ``` The subcommand dials `127.0.0.1:8143/healthz` in-process and exits 0 or 1. That binary is then equally usable as a scheduler's exec-style probe, so one implementation serves both worlds. ## Design rules for the check itself - **Keep it shallow.** A liveness-style check should prove the process is serving, not that every dependency is up. If the check touches the database, a database blip becomes an event that kills or replaces every instance simultaneously — you converted a partial outage into a total one. - **Keep it cheap.** It runs forever, on every instance, at whatever interval the platform picks. - **Do not authenticate it.** The probe usually cannot carry credentials; expose the endpoint on a path that requires none and returns no sensitive detail. - **Distinguish "started" from "ready".** `--start-period` handles slow starts under the engine; a scheduler will usually want a separate readiness signal so it can withhold traffic without killing the instance. - **Use `HEALTHCHECK NONE`** when a base image ships a check that is wrong for your process — inheritance is otherwise silent.