Keycloak

1
<#import "/templates/guide.adoc" as tmpl>
2
<#import "/templates/kc.adoc" as kc>
3
<#import "/templates/options.adoc" as opts>
4
<#import "/templates/links.adoc" as links>
5

6
<@tmpl.guide
7
title="Enabling {project_name} Health checks"
8
summary="Learn how to enable and use {project_name} health checks"
9
includedOptions="health-enabled">
10

11
{project_name} has built in support for health checks. This {section} describes how to enable and use the Keycloak health checks.
12

13
== {project_name} health check endpoints
14

15
{project_name} exposes 4 health endpoints:
16

17
* `/health/live`
18
* `/health/ready`
19
* `/health/started`
20
* `/health`
21

22
See the https://quarkus.io/guides/smallrye-health#running-the-health-check[Quarkus SmallRye Health docs] for information on the meaning of each endpoint.
23

24
These endpoints respond with HTTP status `200 OK` on success or `503 Service Unavailable` on failure, and a JSON object like the following:
25

26
.Successful response for endpoints without additional per-check information:
27
[source, json]
28
----
29
{
30
    "status": "UP",
31
    "checks": []
32
}
33
----
34

35
.Successful response for endpoints with information on the database connection:
36
[source, json]
37
----
38
{
39
    "status": "UP",
40
    "checks": [
41
        {
42
            "name": "Keycloak database connections health check",
43
            "status": "UP"
44
        }
45
    ]
46
}
47
----
48

49
== Enabling the health checks
50
It is possible to enable the health checks using the build time option `health-enabled`:
51

52
<@kc.build parameters="--health-enabled=true"/>
53

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

56
== Using the health checks
57

58
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 {project_name} container image, local command-based monitoring will not function easily.
59

60
If you are not using {project_name} in a container, use whatever you want to access the health check endpoints.
61

62
=== curl
63

64
You may use a simple HTTP HEAD request to determine the `+live+` or `+ready+` state of {project_name}. `+curl+` is a good HTTP client for this purpose.
65

66
If {project_name} is deployed in a container, you must run this command from outside it due to the previously mentioned security measures. For example:
67

68
[source, bash]
69
----
70
curl --head -fsS http://localhost:8080/health/ready
71
----
72

73
If the command returns with status 0, then {project_name} is `+live+` or `+ready+`, depending on which endpoint you called. Otherwise there is a problem.
74

75
=== Kubernetes
76

77
Define a https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/#http-probes[HTTP Probe] so that Kubernetes may externally monitor the health endpoints. Do not use a liveness command.
78

79
=== HEALTHCHECK
80

81
The Dockerfile image `+HEALTHCHECK+` instruction defines a command that will be periodically executed inside the container as it runs. The {project_name} container does not have any CLI HTTP clients installed. Consider installing `+curl+` as an additional RPM, as detailed by the <@links.server id="containers" /> {section}. Note that your container may be less secure because of this.
82

83
== Available Checks
84

85
The table below shows the available checks.
86

87
[%autowidth]
88
|===
89
|Check | Description | Requires Metrics
90

91
|Database
92
|Returns the status of the database connection pool.
93
|Yes
94

95
|===
96

97
For some checks, you'll need to also enable metrics as indicated by the `Requires Metrics` column. To enable metrics
98
use the `metrics-enabled` option as follows:
99

100
<@kc.build parameters="--health-enabled=true --metrics-enabled=true"/>
101

102
</@tmpl.guide>
103