Chapter 19. Enabling Red Hat build of Keycloak Health checks

Red Hat build of Keycloak exposes 4 health endpoints:

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": []
}

{
    "status": "UP",
    "checks": [
        {
            "name": "Keycloak database connections health check",
            "status": "UP"
        }
    ]
}

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

bin/kc.[sh|bat] build --health-enabled=true

By 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 Red Hat build of Keycloak container image, local command-based monitoring will not function easily.

If you are not using Red Hat build of Keycloak in a container, use whatever you want to access the health check endpoints.

curl --head -fsS http://localhost:9000/health/ready

curl --head -fsS http://localhost:9000/health/ready

The table below shows the available checks.

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

bin/kc.[sh|bat] build --health-enabled=true --metrics-enabled=true