Updated Traefik passthrough README with health check and configuration details by ruchikajha95 · Pull Request #748 · keycloak/keycloak-quickstarts

ruchikajha95 · 2026-04-22T15:10:39Z

Updated Traefik passthrough README with health check and configuration details

Signed-off-by: Ruchika [email protected]

… details Signed-off-by: Ruchika <[email protected]>

pruivo · 2026-04-22T17:23:42Z

We forgot about CI. Please add a job to https://github.com/keycloak/keycloak-quickstarts/blob/1b60f49d7d809599c3cf0d4ca9916dc71c4be715/.github/workflows/workflow-ci.yml

Signed-off-by: Ruchika <[email protected]>

ahus1

Thank you for the PR. I suppose the traefik file is missing the services and routers entries. Can you please check?

Signed-off-by: Ruchika <[email protected]>

ahus1

I see you previously experimented with a TCP check. What was the result with that?

BTW, one can set KC_HTTP_MANAGEMENT_SCHEME: http so the management endpoint doesn't run HTTPS which might open the door for the TCP based check. Still I wasn't able to get it to work, and traefik didn't provide me with the response it received from Keycloak, so it was hard to debug.

When in debug mode, I figured out that "\n" was taken as a literal string, and not as a line break. I then use multi-line YAML, which looked better, but then didn't succeed.

If we go down the route of not having a readiness probe, this should be reflected in the README, possibly with a link to the open issue.

Without a probe, we would also need to disable server-async-bootstrap (this is probably why the tests are failing).

Without a probe, there is also not much benefit for a graceful shutdown as it is scripted here. We would actually need to have a different playbook for a graceful shutdown where one would first need to update the keycloak.yaml to remove one of the servers before shutting it down.

pruivo · 2026-04-23T13:14:29Z

@ahus1 I didn't experiment with HTTP, but the probe in Traefik compares with all the server response (looking at the source code).
I'm guessing the expected string would need the HTTP response (headers, status, etc) + Quarkus Health Check JSON response.

+1 to disable async-bootstrap and +1 to set shutdown-delay to zero.

ahus1 · 2026-04-23T13:44:33Z

the probe in Traefik compares with all the server response (looking at the source code)

Oh, that gives me an idea! See the next push with a suggested fix that works for me locally.

Signed-off-by: Alexander Schwartz <[email protected]>

ahus1 · 2026-04-23T14:58:30Z

@pruivo / @ruchikajha95 - I've pushed the changes, and the CI is happy :D

Now I wonder if you think this check is good and you want to continue with it and update the docs, or if you think this check is too fragile.

I'd argue in favor of keeping it, as having a readiness probe gives you lots of benefits like split-brain detection, a node that is too overloaded, can't talk to the database, better shutdown behavior, etc.

pruivo · 2026-04-23T15:25:38Z

@ahus1 It looks fragile (and ugly), mainly because of the charset that may change by the user. But I'm ok to have it in the quickstarts.

ruchikajha95 · 2026-04-23T15:32:41Z

@pruivo / @ruchikajha95 - I've pushed the changes, and the CI is happy :D

Now I wonder if you think this check is good and you want to continue with it and update the docs, or if you think this check is too fragile.

I'd argue in favor of keeping it, as having a readiness probe gives you lots of benefits like split-brain detection, a node that is too overloaded, can't talk to the database, better shutdown behavior, etc.

Thank you @ahus1 , @pruivo .I was experimenting with something similar yesterday but couldn't get it to work on my end !glad it worked now! I'm happy to keep the changes in the quickstart and proceed with the corresponding documentation updates in the Keycloak repo.!

ahus1 · 2026-04-23T16:31:16Z

I'm happy to keep the changes in the quickstart and proceed with the corresponding documentation updates in the Keycloak repo!

Thanks. Yes, please proceed.

ahus1

Thank you for the PR. After my latest push with the health check, the README is unfortunately out of date. Can you please update it?

Please review if you think any other items would require a longer explanation of "why" and possible alternatives.

ahus1 · 2026-04-24T08:36:43Z

+Since Traefik operates at the TCP layer for TLS passthrough, it performs TCP-level health checks on each backend server.
+
+```yaml
+        healthCheck:
+          interval: "5s"
+          timeout: "3s"


After my change to keycloak.yaml this is not outdated. Can you please update the README that it matches the configuration?

It would be good to have a paragraph about the why the health check is chosen, what possible downsides are (fragile, no TLS), and what the alternatives are (simple TCP, different shutdown procedure, no readiness check, no split brain detection).

pruivo · 2026-04-24T09:59:41Z

@ruchikajha95, the README in proxy/README.md needs to be updated too.

pruivo · 2026-04-24T10:06:40Z

+
+## Architecture
+
+![Architecture diagram](traefikArchitechture.png)


The image says TCP passthrough. Did you mean TLS passthrough?

pruivo · 2026-04-24T10:11:57Z

+      postgres:
+        condition: service_healthy
+    networks:
+      - frontend


This is wrong; Keycloak must use only the backend network.

pruivo · 2026-04-24T10:12:48Z

+**Traefik health check :**
+
+**Traefik health check:**


duplicated header.

pruivo · 2026-04-24T10:14:38Z

+api:
+  insecure: true
+```
+- `insecure: true` exposes the Traefik dashboard without any authentication. This is intended for local development and debugging only and must never be used in production.


It says the same thing twice:

exposes the Traefik dashboard without any authentication and Enables the Traefik dashboard on port 8080 without authentication

This is intended for local development and debugging and for local testing only.

pruivo · 2026-04-24T10:17:31Z

+       serversTransports:
+       kc-passthrough:
+         proxyProtocol:
+           version: 2


Indentation is off

Suggested change

serversTransports:

kc-passthrough:

proxyProtocol:

version: 2

serversTransports:

kc-passthrough:

proxyProtocol:

version: 2

pruivo · 2026-04-24T10:20:59Z

+          timeout: "3s"
+```
+
+- Traefik checks each backend every 5s, marking a server as unhealthy if it does not respond within 3s. Unhealthy backends are automatically removed from the load balancer rotation and re-added once they recover


To avoid duplicating the configuration, I would remove this section and move this line after line 167

Don't forget to mention CLI option KC_HTTP_MANAGEMENT_SCHEME.

pruivo · 2026-04-24T10:21:07Z

+          - address: "keycloak1:8443"
+          - address: "keycloak2:8443"
+```
+- Defines the two Keycloak backend servers. Traefik distributes incoming TCP connections across both instances using round-robin load balancing.


pruivo · 2026-04-24T10:21:16Z

+```
+- Defines the two Keycloak backend servers. Traefik distributes incoming TCP connections across both instances using round-robin load balancing.
+
+- `docker run --rm --network passthrough_backend alpine nc -zv keycloak1 9000`  verify the management port is reachable within the internal Docker network (as seen in the nc test)


What is this!?

pruivo · 2026-04-24T10:21:45Z

@@ -0,0 +1,14 @@
+


nitpicking, remove empty line

pruivo · 2026-04-24T10:22:46Z

Compress the image or convert to SVG. 5MB is way too big 😃

update Traefik passthrough README with health check and configuration…

b0514ff

… details Signed-off-by: Ruchika <[email protected]>

ruchikajha95 requested review from ahus1 and pruivo April 22, 2026 15:10

ruchikajha95 self-assigned this Apr 22, 2026

pruivo reviewed Apr 22, 2026

View reviewed changes

Comment thread proxy/traefik/passthrough/haproxy.cfg Outdated

pruivo reviewed Apr 22, 2026

View reviewed changes

Comment thread proxy/traefik/passthrough/README.md Outdated

Pr review comments

85973f9

Signed-off-by: Ruchika <[email protected]>

ahus1 requested changes Apr 23, 2026

View reviewed changes

Comment thread proxy/traefik/passthrough/traefik.yaml

Pr review comments latest

f997ef8

Signed-off-by: Ruchika <[email protected]>

ahus1 requested changes Apr 23, 2026

View reviewed changes

ahus1 self-assigned this Apr 23, 2026

Try out with health check

1ffbe2e

Signed-off-by: Alexander Schwartz <[email protected]>

ruchikajha95 marked this pull request as ready for review April 23, 2026 17:01

ahus1 requested changes Apr 24, 2026

View reviewed changes

pruivo suggested changes Apr 24, 2026

View reviewed changes


		## Architecture

		![Architecture diagram](traefikArchitechture.png)

Conversation

ruchikajha95 commented Apr 22, 2026

Uh oh!

Uh oh!

Uh oh!

pruivo commented Apr 22, 2026

Uh oh!

ahus1 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

ahus1 left a comment

Choose a reason for hiding this comment

Uh oh!

pruivo commented Apr 23, 2026

Uh oh!

ahus1 commented Apr 23, 2026

Uh oh!

ahus1 commented Apr 23, 2026

Uh oh!

pruivo commented Apr 23, 2026

Uh oh!

ruchikajha95 commented Apr 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ahus1 commented Apr 23, 2026

Uh oh!

ahus1 left a comment

Choose a reason for hiding this comment

Uh oh!

ahus1 Apr 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pruivo commented Apr 24, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

ruchikajha95 commented Apr 23, 2026 •

edited

Loading

ahus1 Apr 24, 2026 •

edited

Loading