Separate Kubernetes API server readiness from liveness

Bottom line: Choose the API server health signal from the action it should drive. A restart decision, a decision to stop sending traffic and an operator investigation need separate entries in the control-plane runbook.

Source fact: documented behavior

The Kubernetes API health endpoints documentation is the primary reference.

The aggregate livez endpoint addresses whether the API server needs restarting, while readyz addresses whether it can accept traffic. The guide directs machines to use HTTP status codes and reserves verbose output for human diagnosis. Its separate individual-health-check subsection is labeled alpha since Kubernetes 1.37; those per-check endpoints are outside this article.

What the source does not establish

This article covers the aggregate control-plane endpoints, not application-container probe configuration or individual alpha checks. An endpoint response is one observation. It does not establish that every cluster workload, dependency or administrator workflow is functioning. Keep authentication and the approved connection method within the deployment-specific runbook.

Applicability questions

• Which decision will consume the check: restart, traffic routing or investigation?
• Which API server instance and approved authenticated route are being tested?
• Does automation use the HTTP status or parse diagnostic text?
• What evidence will confirm recovery beyond the health response?

DSE recommendation: map each signal to an action

DSE recommends writing two explicit control-plane decisions before changing a health consumer. Name the component that can restart an API server and the component that can stop routing requests to one. Have their owners identify which aggregate endpoint each uses and what happens when the request itself cannot be completed.

Keep the machine contract small. Record the endpoint, response status, observation time and server identity. Treat a connection failure as its own diagnostic condition rather than manufacturing a successful response from a missing body. Review any existing text parser against the documented status-code contract before relying on it.

Give operators a separate diagnostic step. Use the documented authenticated kubectl get example with --raw when that access method is appropriate, and retain the verbose checks for investigation. Do not copy the page’s local TLS-bypass example into an ordinary monitoring runbook. Select the approved trust and authentication configuration for the actual cluster.

Document the return-to-service decision as well as the failure action. Require the responsible operator to connect the endpoint result with the maintenance or incident timeline. Keep a temporary diagnostic exclusion out of the normal machine check unless a separately reviewed requirement explicitly calls for it.

Verification and evidence

Proposed verification, not performed: prepare three labeled inputs at the health consumer boundary: a successful aggregate status, a failed status and an unavailable endpoint. Confirm the intended restart or routing branch without disrupting an unapproved control plane. Identify injected inputs clearly; they are not evidence that an API server entered those states.

Separately, obtain an authorized verbose response and ask an operator to explain which checks require investigation. Retain the actual HTTP status beside that text. Review whether the automation would reach the same decision if human-readable wording changed while the status remained the same. Record the chosen endpoint, authenticated route, consumer behavior and unresolved conditions with the runbook revision.

Official references

• Kubernetes API health endpoints — Kubernetes.

Source review completed October 28, 2026. Recheck the official documentation and deployment-specific applicability before a production change.