Search

Chapter 15. Enabling Red Hat build of Keycloak Health checks

download PDF

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.

15.1. Red Hat build of Keycloak health check endpoints

Red Hat build of 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"
        }
    ]
}

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

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

15.3. 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 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.

15.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 run this command from outside it due to the previously mentioned security measures. For example:

curl --head -fsS http://localhost:8080/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.

15.3.2. Kubernetes

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

15.3.3. HEALTHCHECK

The Dockerfile image HEALTHCHECK instruction defines a command that will be periodically executed inside the container as it runs. The Red Hat build of Keycloak container does not have any CLI HTTP clients installed. Consider installing curl as an additional RPM, as detailed by the Running Red Hat build of Keycloak in a container chapter. Note that your container may be less secure because of this.

15.4. Available Checks

The table below shows the available checks.

CheckDescriptionRequires 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

15.5. 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)

Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.