Change:
This is a Feature Request During creating this PR: I found out that the and endpoints of the kube-apiserver are not really document. Also the documentation should highlight that and are the new endpoints which should be used (otherwise some flags like and will be ignored. What would you like to be <!-- Describe as precisely as possible how this feature/enhancement should work from the user perspective. What should be changed, etc. --It would be nice to describe the differences of the endpoints and when the specific endpoints should be used (or not). Probably a sub page in would be nice (or maybe it fits somewhere else) Why is this needed It would be nice to know what endpoints should be used to create a and a and what are the difference between these 3 endpoints. Comments <!-- Any additional related comments that might help. Drawings/mockups would be extremely helpful (if required). --
/sig network node
actually livez/readyz is kube-apiserver only, so: /remove-sig node network /sig api-machinery though, one way to get the attention of sig-api-machinery would have been to log this issue in k/kubernetes.
/sig docs
this sounds like reference documentation to me, rather than a task.
That's right, do you have any preferred place where we could put this documentation? If so I would start writing down some documentation that can be reviewed by api-machinery.
There's already (generated documentation). Maybe add (currently a 404)?
If there's a place in the code for kube-apiserver to add text that ends up on and explains the health checks, that's also a valid approach.
I think is the best place, I don't think that the command line reference is the best place. I try to write something down this week.
/language en

Discussion:
<ins> --- title: Kubernetes API health endpoints reviewers: - logicalhan content_type: concept weight: 50 --- <!-- overview --> The Kubernetes {{< glossary_tooltip term_id="kube-apiserver" text="API server" >}} provides API endpoints to indicate the current status of the API server. This page describes these API endpoints and explains how you can use them. <!-- body --> ## API endpoints for health The Kubernetes API server provides 3 API endpoints (`healthz`, `livez` and `readyz`) to indicate the current status of the API server. The `healthz` endpoint is deprecated (since Kubernetes v1.16), and you should use the more specific `livez` and `readyz` endpoints instead. The `livez` endpoint can be used with the `--livez-grace-period` [flag](/docs/reference/command-line-tools-reference/kube-apiserver) to specify the startup duration. For a graceful shutdown you can specify the `--shutdown-delay-duration` [flag](/docs/reference/command-line-tools-reference/kube-apiserver) with the `/readyz` endpoint. Machines that check the `health`/`livez`/`readyz` of the API server should rely on the HTTP status code. A status code `200` indicates the the API server is `healthy`/`live`/`ready`, depending of the called endpoint. The more verbose options shown below are intended to be used by human operators to debug their cluster or specially the state of the API server. The following examples will show how you can interact with the health API endpoints. For all endpoints you can use the `verbose` parameter to print out the checks and their status. This can be useful for a human operator to debug the current status of the Api server, it is not intended to be consumed by a machine: ```shell curl -k https://localhost:6443/livez?verbose ``` or from a remote host with authentication: ```shell kubectl get --raw='/readyz?verbose' ``` The output will look like this: [+]ping ok [+]log ok [+]etcd ok [+]poststarthook/start-kube-apiserver-admission-initializer ok [+]poststarthook/generic-apiserver-start-informers ok [+]poststarthook/start-apiextensions-informers ok [+]poststarthook/start-apiextensions-controllers ok [+]poststarthook/crd-informer-synced ok [+]poststarthook/bootstrap-controller ok [+]poststarthook/rbac/bootstrap-roles ok [+]poststarthook/scheduling/bootstrap-system-priority-classes ok [+]poststarthook/start-cluster-authentication-info-controller ok [+]poststarthook/start-kube-aggregator-informers ok [+]poststarthook/apiservice-registration-controller ok [+]poststarthook/apiservice-status-available-controller ok [+]poststarthook/kube-apiserver-autoregistration ok [+]autoregister-completion ok [+]poststarthook/apiservice-openapi-controller ok healthz check passed The Kubernetes API server also supports to exclude specific checks. The query parameters can also be combined like in this example: ```shell curl -k 'https://localhost:6443/readyz?verbose&exclude=etcd' ``` The output show that the `etcd` check is excluded: [+]ping ok [+]log ok [+]etcd excluded: ok [+]poststarthook/start-kube-apiserver-admission-initializer ok [+]poststarthook/generic-apiserver-start-informers ok [+]poststarthook/start-apiextensions-informers ok [+]poststarthook/start-apiextensions-controllers ok [+]poststarthook/crd-informer-synced ok [+]poststarthook/bootstrap-controller ok [+]poststarthook/rbac/bootstrap-roles ok [+]poststarthook/scheduling/bootstrap-system-priority-classes ok [+]poststarthook/start-cluster-authentication-info-controller ok [+]poststarthook/start-kube-aggregator-informers ok [+]poststarthook/apiservice-registration-controller ok [+]poststarthook/apiservice-status-available-controller ok [+]poststarthook/kube-apiserver-autoregistration ok [+]autoregister-completion ok [+]poststarthook/apiservice-openapi-controller ok [+]shutdown ok healthz check passed ## Individual health checks {{< feature-state state="alpha" >}} Each individual health check exposes an http endpoint and could can be checked individually. The schema for the individual health checks is `/livez/<healthcheck-name>` where `livez` and `readyz` and be used to indicate if you want to check thee liveness or the readiness of the API server. The `<healthcheck-name>` path can be discovered using the `verbose` flag from above and take the path between `[+]` and `ok`. These individual health checks should not be consumed by machines but can be helpful for a human operator to debug a system: ```shell curl -k https://localhost:6443/livez/etcd ``` </ins>