Health checks for APIs: /healthz, /readyz, /livez, version, and metrics in OpenAPI
A single /health endpoint that checks the database, the cache, and three downstream services, and returns 500 if any of them is briefly unreachable, is actively harmful. Kubernetes interprets a failed liveness probe as "this process is dead," kills the container, and starts a new one, which then hammers the same struggling dependency and makes the outage worse. The probe answered the wrong…
The /health endpoint, which checks the health of APIs, can be /livez, /readyz, /livez, version, and metrics in OpenAPI. Placing dependency checks in the /livez probe can cause more harm than good, as Kubernetes may kill the container if any dependency is unreachable, leading to a cascade of restarts and sending traffic to unresponsive instances.
Thus, the /livez probe should only check if the process is alive and not wedged. The /readyz probe should verify if the instance can serve requests right now, and stop sending traffic if not. The /startz probe checks if slow initialization has finished. The responses to these probes should be simple, fast, and machine-readable, with a healthy response being "ok" and a failed response listing the failing components without disclosing internal details.
The probes should have short timeouts and not cause side effects. Detailed health information should be protected with circuit breakers to prevent cascading failures. The /version and /metrics endpoints should be accessible only internally, exposing only necessary information and avoiding secrets, connection strings, internal IPs, or stack traces.
Documenting these operational endpoints in OpenAPI and separating them from public business APIs ensures a safe and effective health-check system.
Written by urgent.news from Dev.to's reporting — not their text. Machine-written — may contain errors; check the original before relying on it.