Docker healthchecks: what they actually measure and what you shouldn't promise

Docker healthchecks: what they actually measure and what you shouldn't promise

The right way to know if your container is healthy is to stop asking the container if it's healthy. I know that sounds weird. Let me explain why a HEALTHCHECK that returns 200 OK might be lying straight to your face.

The problem isn't the instruction itself. It's the implicit promise we attach to it: if the healthcheck passes, the app works. That's where it breaks down. A process can respond on /healthz and simultaneously have a disconnected database, a saturated queue, or a hung internal worker. Docker's HEALTHCHECK knows nothing about any of that unless you explicitly teach it.

My thesis: HEALTHCHECK is a useful but narrow operational signal. Telling someone "if the healthcheck passes, the service is fine" is promising something the tool simply cannot deliver.

What the official docs say — and what they don't