The official Keycloak Docker image should have `curl` installed #39376

TheKnarf · 2025-04-30T14:37:43Z

TheKnarf
Apr 30, 2025

Description

Some platform needs curl to do healthchecks. They'll use the Docker image itself and run the healthcheck inside the image.

A simple example might be Docker Compose where you want the following to work:

services:
  keycloak:
    image: quay.io/keycloak/keycloak:26.1.3
    ports:
      - "8081:8080"
    environment:
      KC_BOOTSTRAP_ADMIN_USERNAME: "admin"
      KC_BOOTSTRAP_ADMIN_PASSWORD: "admin"
    command: start-dev
    volumes:
      - keycloak_data:/opt/keycloak/data/
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/"]
      interval: 10s
      timeout: 5s
      start_period: 30s
      retries: 20

There is a discussion over here looking at other ways of doing it, but all of those seem wildly impractical, and it seems like it would make more sense for this to just ship with the image.

Discussion

No response

Motivation

It should be easy to setup health checks, some platforms require curl (or a similar command) to exist in the Docker image to perform health checks (Docker Compose, Docker Swarm, etc).

Details

Add curl as an package to the official Docker image.

shawkins · 2025-04-30T14:42:16Z

shawkins
Apr 30, 2025
Collaborator

See #17273 and other similar discussions / issues. You may create a custom image if you need curl. There are no plans to add it to the base image.

0 replies

TheKnarf · 2025-04-30T14:43:10Z

TheKnarf
Apr 30, 2025
Author

So everyone who uses Docker Swarm and similar platforms have to create their own Image? That doesn't seem logical.

0 replies

TheKnarf · 2025-04-30T14:45:06Z

TheKnarf
Apr 30, 2025
Author

If the container doesn't want to ship curl then they should still ship an official "healthcheck.sh" command. You can't except people to run the official container in production without it.

0 replies

shawkins · 2025-04-30T15:02:25Z

shawkins
Apr 30, 2025
Collaborator

@TheKnarf you free to raise an enhancement about what a shell based health check would look like.

You can also see a recent discussion about using just shell commands, but it is applicable to situations with http enabled #38131 While that pr wasn't committed you may consider using that along with leaving http enabled - even if you intend to be behind a reencrypt or passthrough proxy. Just don't generally expose the http port.

cc @vmuzikar @ahus1

0 replies

TheKnarf · 2025-04-30T15:07:37Z

TheKnarf
Apr 30, 2025
Author

I think there should just be a bin/kc.sh healthcheck subcommand then.

0 replies

ahus1 · 2025-04-30T15:59:37Z

ahus1
Apr 30, 2025
Collaborator

@shawkins - I suppose we could add a minimal HTTP client that would execute a HTTP get request to a URL provided as a parameter as a new command.

It would be handled on the Picoli side of things, and wouldn't start up Quarkus. It could look like:

bin/kc.sh checkhttp [-v] <url>

Starting up Java would be expensive, still it would come out-of-the box without additional CVEs.

To minimize the overhead, we could wrap it a single class like the following. Note that I tested it with java TestHttp.java https://www.keycloak.org/xxx but unfortunately it didn't return the exit code in this auto-compile mode. The return code only worked when I first compiled it.

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.ArrayList;
import java.util.Arrays;

public class TestHttp {
    public static void main (String[] _args) throws Exception {
        boolean verbose = false;
        ArrayList<String> args = new ArrayList<>(Arrays.asList(_args));
        if (!args.isEmpty() && args.get(0).equals("-v")) {
            args.remove(0);
            verbose = true;
        }
        if (args.isEmpty()) {
            System.err.println("Usage: java -cp . TestHttp [-v] <url>");
            System.exit(2);
        }
        try (HttpClient client = HttpClient.newHttpClient()) {
            HttpRequest request = HttpRequest.newBuilder()
                    .uri(URI.create(args.get(0)))
                    .build();

            HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
            System.out.println("Status Code: " + response.statusCode());
            if (verbose) {
                System.out.println(response.body());
            }
            if (response.statusCode() < 200 || response.statusCode() > 300) {
                System.out.println("problem");
                System.exit(1);
            }
        } catch (RuntimeException e) {
            System.err.println(e.getMessage());
            System.exit(1);
        }
    }
}

We should run it with some (static) JVM and a fixed memory size to avoid situations where it runs off with too much memory.

WDYT?

0 replies

vmuzikar · 2025-04-30T16:10:35Z

vmuzikar
Apr 30, 2025
Collaborator

We've discussed it in the past, IIRC. My thought here would be that using a Java client for probes is not ideal due to performace (spinning up another JVM for every probes ping). Possibly native mode would help.

0 replies

ahus1 · 2025-04-30T16:54:00Z

ahus1
Apr 30, 2025
Collaborator

I agree it is not ideal, but I doubt we would have a native mode soon (which we would need to compile for two architectures ARM and non-ARM, which is IMHO a pain). So maybe the non-native Java option is good enough?

0 replies

shawkins · 2025-04-30T17:15:23Z

shawkins
Apr 30, 2025
Collaborator

Moved to a discussion.

bin/kc.sh checkhttp [-v]

I would keep it as a separate script as to not clutter kc.sh / kc.bat - if anything I'd like to remove more logic from those scripts.

My thought here would be that using a Java client for probes is not ideal due to performace (spinning up another JVM for every probes ping)

It's not too far of a stretch to make #38131 work for this purpose in general.

If we expanded our healthchecks to also check the health our https interface (might not work when client auth is required), then a health check against the management port configured for http would be good enough - and not require a separate java process launch.

If you are in edge mode, typically only http will be enabled - and https won't need to be tested regardless.

If you are in passthrough or reencrypt, then the management interface could be left as http - but we currently missing a configuration option for that.

For these situations we can recommend using localhost as the management host so that it is not broadly accessible.

Only if someone truly wants to expose the management interface as https would there be a problem - even then we could consider still exposing a limited health check over http and rely upon quarkusio/quarkus#47531 to keep the main http interface exposed only to localhost.

Are we sure that we're making the right assumptions with effectively securing the management port by default when https is enabled?

2 replies

vmuzikar May 5, 2025
Collaborator

I like the idea of in essence enforcing health checks to be always HTTP. It also makes sense from the server perspective, HTTPS is more expensive and not really needed for a basic health check.

shawkins May 6, 2025
Collaborator

Based upon some internal discussion, created #39506 to capture how we can reasonably offer an http health check.

The official Keycloak Docker image should have curl installed #39376

Uh oh!

Uh oh!

TheKnarf Apr 30, 2025

Description

Discussion

Motivation

Details

Replies: 9 comments · 2 replies

Uh oh!

shawkins Apr 30, 2025 Collaborator

Uh oh!

TheKnarf Apr 30, 2025 Author

Uh oh!

TheKnarf Apr 30, 2025 Author

Uh oh!

shawkins Apr 30, 2025 Collaborator

Uh oh!

TheKnarf Apr 30, 2025 Author

Uh oh!

ahus1 Apr 30, 2025 Collaborator

Uh oh!

vmuzikar Apr 30, 2025 Collaborator

Uh oh!

Uh oh!

ahus1 Apr 30, 2025 Collaborator

Uh oh!

Uh oh!

shawkins Apr 30, 2025 Collaborator

Uh oh!

vmuzikar May 5, 2025 Collaborator

Uh oh!

Uh oh!

shawkins May 6, 2025 Collaborator

The official Keycloak Docker image should have `curl` installed #39376

TheKnarf
Apr 30, 2025

Replies: 9 comments 2 replies

shawkins
Apr 30, 2025
Collaborator

TheKnarf
Apr 30, 2025
Author

TheKnarf
Apr 30, 2025
Author

shawkins
Apr 30, 2025
Collaborator

TheKnarf
Apr 30, 2025
Author

ahus1
Apr 30, 2025
Collaborator

vmuzikar
Apr 30, 2025
Collaborator

ahus1
Apr 30, 2025
Collaborator

shawkins
Apr 30, 2025
Collaborator

vmuzikar May 5, 2025
Collaborator

shawkins May 6, 2025
Collaborator