Reference
Health endpoints
The four paths
The relay and the applier each serve the same four paths on --health-listen.
| Path | Returns | Use it for |
|---|---|---|
/livez | 200 unless the phase is stopped or failed; 503 otherwise. | Restart policy. It answers “is this process worth keeping”. |
/readyz | 200 only when the service is accepting work; 503 otherwise. | Load-balancer and rollout gating. Draining reads 503 immediately. |
/healthz | 200 with the full snapshot as JSON, always. | Debugging and dashboards. Never as a probe. |
/metrics | 200, Prometheus text exposition. | Scraping. |
Liveness is not readiness
/livez and /readyz answer different questions, and wiring both to the same probe is the common mistake. A service that is running but blocked — invalid slot, incomplete broker topology, unreconciled writer intent — is alive and not ready. Restarting it will not help; it needs an operator. Point your liveness probe at /livez or you will restart-loop a process that is correctly refusing to proceed.
/healthz returns 200 even when the service is blocked. It is for debugging and dashboards and must never be used as a probe.
Legal phase and readiness combinations
An illegal combination is a validation error, not a state you can observe.
| Phase | Readiness | Accepting work |
|---|---|---|
starting · draining · stopped | not_ready | no |
failed | blocked | no |
running | ready or degraded | yes |
running | backpressured or blocked | no |
degraded, backpressured and blocked always carry a reason_code — lowercase, digits and underscores, so it is safe to route on.
Every phase and readiness value
| Field | Values |
|---|---|
phase | starting · running · draining · stopped · failed |
readiness | not_ready · ready · degraded · backpressured · blocked |
Generated from the repository at
347a884 by tools/gen_reference.py. If this page and the
code disagree, the code is right and this page is a bug.