Chapter 2. Tracking instance status with health checks
Check if an instance has finished its start up and is ready to serve requests by calling its health REST endpoints.
Red Hat build of Keycloak has built in support for health checks. This chapter describes how to enable and use the Red Hat build of Keycloak health checks. The Red Hat build of 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.
2.1. Red Hat build of Keycloak health check endpoints
Red Hat build of Keycloak exposes 4 health endpoints:
-
/health/started- Startup probe used for initial startup of Red Hat build of Keycloak before the liveness probe takes over. -
/health/live- Check if Red Hat build of Keycloak is running. If this fails the application should be discarded (terminated, shutdown) and started again. -
/health/ready- Checks if Red Hat build of Keycloak is ready to process requests or not. Only direct traffic to a newly started instance once the readiness probe succeeds. If this procedure fails, the application is temporarily unavailable to serve new requests, and traffic should be directed elsewhere. -
/health- accumulates all health check procedures in the application.
These endpoints respond with HTTP status 200 OK on success or 503 Service Unavailable on failure, and a JSON object like the following:
Successful response for endpoints without additional per-check information:
{
"status": "UP",
"checks": []
}Successful response for endpoints with additional per-check information:
{
"status": "UP",
"checks": [
{
"name": "Keycloak Initialized",
"status": "UP"
},
{
"name": "Graceful Shutdown",
"status": "UP"
},
{
"name": "Keycloak cluster health check",
"status": "UP"
},
{
"name": "Keycloak database connections async health check",
"status": "UP"
}
]
}See the wire format for a more detailed description.
2.2. Enabling the health checks
It is possible to enable the health checks using the build time option health-enabled:
bin/kc.[sh|bat] build --health-enabled=trueWhen the health endpoints are enabled, async server bootstrap is also enabled by default, resulting in the HTTP ports being open while bootstrapping is in progress. See Configuring Red Hat build of Keycloak for production for more details.
2.3. Using the health checks
Due to security measures that remove curl and other packages from the Red Hat build of Keycloak container image, you are not able to run checks against HTTPS endpoints from within the container.
If you are not using Red Hat build of 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.
2.3.1. curl
You may use a simple HTTP HEAD request to determine the live or ready state of Red Hat build of Keycloak. curl is a good HTTP client for this purpose.
If Red Hat build of 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/ready
If the command returns with status 0, then Red Hat build of Keycloak is live or ready, depending on which endpoint you called. Otherwise there is a problem.
2.3.2. Kubernetes
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.
2.3.3. HEALTHCHECK
The Containerfile HEALTHCHECK instruction defines a command that will be periodically executed inside the container as it runs. While the Red Hat build of 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/9000
The above code depends on the values of the Red Hat build of 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.
the HEALTHCHECK shown is based upon the ready endpoint. This is appropriate for informational purposes or to determine if the container should receive requests. It should not be used to determine if the container needs restarted.
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-schemetohttp. -
or the health checks are enabled for the main interface by setting
http-management-health-enabledtofalseand accessible via HTTP with settinghttp-enabledtotrue. 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.
2.4. Available Checks
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 |
| Graceful shutdown | Will start to return "DOWN" once the pre-shutdown phase started. | No |
| Keycloak Initialized | Returns the status of the server initialization. | 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=true
The cluster health check is only available for clustered setups when the cache transport stacks jdbc-ping or jdbc-ping-udp are used.
2.5. Relevant options
| Type or Values | Default | |
|---|---|---|
| 🛠
|
|
|
'%20d='M201.5%20305.5c-13.8%200-24.9-11.1-24.9-24.6%200-13.8%2011.1-24.9%2024.9-24.9%2013.6%200%2024.6%2011.1%2024.6%2024.9%200%2013.6-11.1%2024.6-24.6%2024.6zM504%20256c0%20137-111%20248-248%20248S8%20393%208%20256%20119%208%20256%208s248%20111%20248%20248zm-132.3-41.2c-9.4%200-17.7%203.9-23.8%2010-22.4-15.5-52.6-25.5-86.1-26.6l17.4-78.3%2055.4%2012.5c0%2013.6%2011.1%2024.6%2024.6%2024.6%2013.8%200%2024.9-11.3%2024.9-24.9s-11.1-24.9-24.9-24.9c-9.7%200-18%205.8-22.1%2013.8l-61.2-13.6c-3-.8-6.1%201.4-6.9%204.4l-19.1%2086.4c-33.2%201.4-63.1%2011.3-85.5%2026.8-6.1-6.4-14.7-10.2-24.1-10.2-34.9%200-46.3%2046.9-14.4%2062.8-1.1%205-1.7%2010.2-1.7%2015.5%200%2052.6%2059.2%2095.2%20132%2095.2%2073.1%200%20132.3-42.6%20132.3-95.2%200-5.3-.6-10.8-1.9-15.8%2031.3-16%2019.8-62.5-14.9-62.5zM302.8%20331c-18.2%2018.2-76.1%2017.9-93.6%200-2.2-2.2-6.1-2.2-8.3%200-2.5%202.5-2.5%206.4%200%208.6%2022.8%2022.8%2087.3%2022.8%20110.2%200%202.5-2.2%202.5-6.1%200-8.6-2.2-2.2-6.1-2.2-8.3%200zm7.7-75c-13.6%200-24.6%2011.1-24.6%2024.9%200%2013.6%2011.1%2024.6%2024.6%2024.6%2013.8%200%2024.9-11.1%2024.9-24.6%200-13.8-11-24.9-24.9-24.9z'/%3e%3c/svg%3e){kind=small}