Enabling Keycloak Health checks

Learn how to enable and use Keycloak health 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

Keycloak health check endpoints

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:

Successful response for endpoints without additional per-check information:
{
    "status": "UP",
    "checks": []
}
Successful response for endpoints with information on the database connection:
{
    "status": "UP",
    "checks": [
        {
            "name": "Keycloak database connections health check",
            "status": "UP"
        }
    ]
}

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=true

By default, no check is returned from the health endpoints.

Using the health checks

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.

curl

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:9000/health/ready

If the command returns with status 0, then Keycloak is live or ready, depending on which endpoint you called. Otherwise there is a problem.

Kubernetes

Define a HTTP Probe so that Kubernetes may externally monitor the health endpoints. Do not use a liveness command.

HEALTHCHECK

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

Available Checks

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

Relevant options

Value

health-enabled

If the server should expose health check endpoints.

If enabled, health checks are available at the /health, /health/ready and /health/live endpoints.

CLI: --health-enabled
Env: KC_HEALTH_ENABLED

true, false (default)

On this page