Health check: definition and meaning
A health check is a small, repeatable request that reports whether a service is alive and able to do its job. A process manager or orchestrator uses the answer to restart a process, hold back traffic, or decide what starts first.
Liveness and readiness
Two questions get mixed up under the name health check.
- Liveness: is this process still working, or stuck so badly that restarting it is the right move? In Kubernetes, the kubelet restarts a container that repeatedly fails its liveness probe. The documentation’s example is a deadlock, where the application is running but cannot make progress.
- Readiness: is this process ready to take traffic right now? A server can be alive while it warms a cache, runs migrations, or waits for a database. When a readiness probe fails, Kubernetes removes the Pod’s IP address from the endpoints of the matching Services. The container is not restarted. It stops receiving requests.
Kubernetes adds a third, the startup probe. While one is configured, liveness and readiness checks stay disabled until it succeeds. A probe can be an HTTP GET request, a TCP connection check, a gRPC call, or a command run inside the container. For an HTTP GET, any status code from 200 up to but not including 400 counts as success.
Keep the two apart. A liveness check that calls the database can turn a database outage into a restart loop: every instance fails the check at once, and restarting a container does not bring the database back. Dependency checks belong in readiness.
Local development
On a laptop there is usually no orchestrator, and the check is much simpler: one HTTP GET to the dev server’s URL with a short timeout. The two questions still exist. A process manager that restarts a crashed server is acting on liveness. A start order that waits for the API before launching the web app is acting on readiness.
Which status codes count as healthy is a choice. A dev server often has no health route, and its home page may return 404 while the server is perfectly able to serve. In a test with curl 8.5.0 against a throwaway local server that answered 404 and then 500, the two forms below behaved differently:
curl -s -o /dev/null --max-time 4 http://127.0.0.1:3000/ # exit 0 on a 404 or 500
curl -fs -o /dev/null --max-time 4 http://127.0.0.1:3000/ # exit 22 on a 404 or 500Without -f, curl exits 0 for any HTTP answer and fails only when nothing answers: exit 7 for a refused connection, exit 28 for a timeout. With -f, any status of 400 or above makes curl exit 22.
Listening is not healthy
A TCP connection proves that something is listening. An HTTP response proves that the application answered. Check the second one if you can.
In Rig
- Rig polls every 5 seconds. For each project it probes the first answering URL from the local URL, custom local URL, HTTPS URL, and Valet URL, with an HTTP GET and a 4 second timeout.
- A status from 200 to 499 is healthy. A 5xx status or an error is unhealthy. With no URL to probe, the state is unknown. A 404 from a dev server with no health route therefore reads as healthy, unlike a Kubernetes HTTP probe, which stops at 399.
- A
localhostloopback URL is rewritten to127.0.0.1before probing. For*.localhost,.test, and.localhosts, Rig does not verify the local HTTPS certificate. - Group start uses health-aware ordering. See Start order and health.
Related terms
- Glossary
Process manager
A process manager starts programs, tracks them, captures their output, and decides what happens when they exit: restart, stay stopped, or report the failure.
- Glossary
Sidecar process
A sidecar is a helper that runs beside a main application and supports it. In Kubernetes it is a container in the same Pod.
- Glossary
localhost
localhost is the reserved hostname for the machine you are on. What it is, how it works, and a common confusion.
Sources
See how Rig fits in
Rig is a Mac app that starts, stops, and watches the processes in a project from one window. The knowledge base explains each part in plain language.