Kubernetes API health endpoints

The Kubernetes 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.

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 to specify the startup duration. For a graceful shutdown you can specify the --shutdown-delay-duration flag with the /readyz endpoint. Machines that check the healthz/livez/readyz of the API server should rely on the HTTP status code. A status code 200 indicates the API server is healthy/live/ready, depending on the called endpoint. The more verbose options shown below are intended to be used by human operators to debug their cluster or understand 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:

  1. curl -k https://localhost:6443/livez?verbose

or from a remote host with authentication:

  1. kubectl get --raw='/readyz?verbose'

The output will look like this:

  1. [+]ping ok
  2. [+]log ok
  3. [+]etcd ok
  4. [+]poststarthook/start-kube-apiserver-admission-initializer ok
  5. [+]poststarthook/generic-apiserver-start-informers ok
  6. [+]poststarthook/start-apiextensions-informers ok
  7. [+]poststarthook/start-apiextensions-controllers ok
  8. [+]poststarthook/crd-informer-synced ok
  9. [+]poststarthook/bootstrap-controller ok
  10. [+]poststarthook/rbac/bootstrap-roles ok
  11. [+]poststarthook/scheduling/bootstrap-system-priority-classes ok
  12. [+]poststarthook/start-cluster-authentication-info-controller ok
  13. [+]poststarthook/start-kube-aggregator-informers ok
  14. [+]poststarthook/apiservice-registration-controller ok
  15. [+]poststarthook/apiservice-status-available-controller ok
  16. [+]poststarthook/kube-apiserver-autoregistration ok
  17. [+]autoregister-completion ok
  18. [+]poststarthook/apiservice-openapi-controller ok
  19. healthz check passed

The Kubernetes API server also supports to exclude specific checks. The query parameters can also be combined like in this example:

  1. curl -k 'https://localhost:6443/readyz?verbose&exclude=etcd'

The output show that the etcd check is excluded:

  1. [+]ping ok
  2. [+]log ok
  3. [+]etcd excluded: ok
  4. [+]poststarthook/start-kube-apiserver-admission-initializer ok
  5. [+]poststarthook/generic-apiserver-start-informers ok
  6. [+]poststarthook/start-apiextensions-informers ok
  7. [+]poststarthook/start-apiextensions-controllers ok
  8. [+]poststarthook/crd-informer-synced ok
  9. [+]poststarthook/bootstrap-controller ok
  10. [+]poststarthook/rbac/bootstrap-roles ok
  11. [+]poststarthook/scheduling/bootstrap-system-priority-classes ok
  12. [+]poststarthook/start-cluster-authentication-info-controller ok
  13. [+]poststarthook/start-kube-aggregator-informers ok
  14. [+]poststarthook/apiservice-registration-controller ok
  15. [+]poststarthook/apiservice-status-available-controller ok
  16. [+]poststarthook/kube-apiserver-autoregistration ok
  17. [+]autoregister-completion ok
  18. [+]poststarthook/apiservice-openapi-controller ok
  19. [+]shutdown ok
  20. healthz check passed

Individual health checks

FEATURE STATE: Kubernetes v1.29 [alpha]

Each individual health check exposes an HTTP endpoint and 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 the 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:

  1. curl -k https://localhost:6443/livez/etcd