{
"status": "UP",
"checks": []
}Keycloak has built in support for health checks. This guide describes how to enable and use the Keycloak health checks.
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 database connections 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.
It is recommended that the health endpoints be monitored by external HTTP requests. Due to security measures that remove curl and other packages from the Keycloak container image, local command-based monitoring will not function easily.
If you are not using Keycloak in a container, use whatever you want 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 run this command from outside it due to the previously mentioned security measures. For example:
curl --head -fsS http://localhost:8080/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.
The Dockerfile image HEALTHCHECK instruction defines a command that will be periodically executed inside the container as it runs. The Keycloak container does not have any CLI HTTP clients installed. Consider installing curl as an additional RPM, as detailed by the Running Keycloak in a container guide. Note that your container may be less secure because of this.
The table below shows the available checks.
| Check | Description | Requires Metrics |
|---|---|---|
Database |
Returns the status of the database connection pool. |
Yes |
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=true| Value | |
|---|---|
|
|