Keycloak V21 Docker Container Health Check Failing

I am running into an issue when upgrading from v20 to v21 of Keycloak running using Docker. Since updating, the Docker container health check is failing and I am unable to determine the cause.

I have gone through the migration documentation, but am unable to find the change that would break the health checks.

All of my other configuration has remained the same, and is all working with v20. This leads me to believe it is definitely a breaking change in v21.

Solution

Seems like Keycloak v21 uses a minified image, which no longer includes the curl command. This was previously being used to perform the health check against local host.

I found this discussion (https://github.com/keycloak/keycloak/issues/17273) regarding the issue. It provides some more insight into the changes if interested.

A user provided a bash script to perform a similar health check:

#!/bin/bash
exec 3<>/dev/tcp/localhost/8080

echo -e "GET /auth/health/ready HTTP/1.1\nhost: localhost:8080\n" >&3

timeout --preserve-status 1 cat <&3 | grep -m 1 status | grep -m 1 UP
ERROR=$?

exec 3<&-
exec 3>&-

exit $ERROR

Some notes:

This only works for http endpoints on Keycloak localhost
The health check URL should be matched (note the inclusion of /auth/ for backwards compatibility. In later versions, /auth/ can be omitted if not included in your environment variables).
The bash script needs to be copied into your Docker image (if using Docker) and referenced in the health check.

If you are launching it on ECS, the health check block of the Task Definition should be defined similarly to this:

"healthCheck": {
   "command": [
       "CMD-SHELL",
       "bash /complete/path/to/healthcheck/script"
    ],
    "interval": **,
    "timeout": **,
    "retries": **,
    "startPeriod": **
 }