{
"status": "UP",
"checks": []
}Keycloak has built in support for health checks. This guide describes how to enable and use the Keycloak health checks.
The Keycloak health checks are exposed on the management port 9000 by default. For more details, see Configuring the Management Interface
When the http-management-health-enabled option is false the health endpoints will remain on the main HTTP(S) ports, rather than being exposed on the management port.
When this option is false you should block unwanted external traffic to /health at your proxy.
Keycloak exposes 4 health endpoints:
/health/live
/health/ready
/health/started
/health
See the Quarkus SmallRye Health docs for information on the meaning of each endpoint.
These endpoints respond with HTTP status 200 OK on success or 503 Service Unavailable on failure, and a JSON object like the following:
{
"status": "UP",
"checks": []
}{
"status": "UP",
"checks": [
{
"name": "Keycloak cluster health check",
"status": "UP"
},
{
"name": "Keycloak database connections async health check",
"status": "UP"
}
]
}It is possible to enable the health checks using the build time option health-enabled:
bin/kc.[sh|bat] build --health-enabled=trueBy default, no check is returned from the health endpoints.
Due to security measures that remove curl and other packages from the Keycloak container image, you are not able to run checks against HTTPS endpoints from within the container.
If you are not using Keycloak in a container, or if you are running the health checks outside of the container, use any tool to access the health check endpoints.
You may use a simple HTTP HEAD request to determine the live or ready state of Keycloak. curl is a good HTTP client for this purpose.
If Keycloak is deployed in a container, you must use a custom image or run this command from outside it due to the previously mentioned security measures. For example:
curl --head -fsS http://localhost:9000/health/readyIf the command returns with status 0, then Keycloak is live or ready, depending on which endpoint you called. Otherwise there is a problem.
Define a HTTP Probe so that Kubernetes may externally monitor the health endpoints. Do not use a liveness command.
If you configure mTLS with https-client-auth set to required, this configuration is inherited by the management interface. If you have not otherwise configured the usage of HTTP for the health endpoints, you will likely want to set https-management-client-auth to request or none so that a valid client certificate is not required for probe requests.
|
The Containerfile HEALTHCHECK instruction defines a command that will be periodically executed inside the container as it runs. While the Keycloak container does not have any CLI HTTP clients installed, it is possible to leverage BASH support for redirects to TCP sockets and craft a simple HTTP request to the healthcheck endpoint:
{ printf 'HEAD /health/ready HTTP/1.0\r\n\r\n' >&0; grep 'HTTP/1.0 200'; } 0<>/dev/tcp/localhost/9000The above code depends on the values of the Keycloak options such as http-relative-path (http-management-relative-path) and http-management-port. In case those are changed the code needs to be modified accordingly.
If you enable TLS as shown in Configuring TLS, the management interface will also use TLS. Depending upon how the management interface endpoints are intended to be used you can still have plain HTTP health checks if:
the management interface uses HTTP, not HTTPS, by setting http-management-scheme to http.
or the health checks are enabled for the main interface by setting http-management-health-enabled to false and accessible via HTTP with setting http-enabled to true. In this scenario external traffic to the HTTP port (defaults to 8080) or to the health endpoints (defaults to /health) should not be allowed by your proxy.
The table below shows the available checks.
| Check | Description | Requires Metrics |
|---|---|---|
Database |
Returns the status of the database connection pool. |
Yes |
Cluster |
Returns the status of the cluster (network partitions). |
No |
For some checks, you’ll need to also enable metrics as indicated by the Requires Metrics column. To enable metrics
use the metrics-enabled option as follows:
bin/kc.[sh|bat] build --health-enabled=true --metrics-enabled=trueThe cluster health check is only available for clustered setups when the cache transport stacks jdbc-ping or jdbc-ping-udp are used.