Operator: Support for create ingress / route without setting KC_HOSTNAME environment variable in application container #47564

gilvansfilho · 2026-03-28T21:08:00Z

gilvansfilho
Mar 28, 2026

The problem

Currently the operator uses spec.hostname.hostname to define both:

KC_HOSTNAME environment variable
ingress host / route domain

This puts a wall to deploy keycloak with dynamic hostname keeping ingress managed by the operator.

I mean, when both spec.hostname.hostname and spec.hostname.strict are defined operator creates:

a ingress with host equals to spec.hostname.hostname (so a openshift route with domain equals to ingress host)
keycloak container with KC_HOSTNAME equals to spec.hostname.hostname and KC_HOSTNAME_STRICT equals to spec.hostname.strict.

Therefore, if someone tries to configure Keycloak CR as below, wanting to have a dynamic hostname, he will not be able to.

apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
  name: example-keycloak
  namespace: keycloak
spec:
  hostname:
    hostname: keycloak.example.com
    strict: false

As exposed in log KC_HOSTNAME_STRICT is ignored if KC_HOSTNAME is specified and that is exactly what operator does:

2026-03-28 12:06:54,496 INFO [org.keycloak.url.HostnameV2ProviderFactory] (main) If hostname is specified, hostname-strict is effectively ignored

When you need to deploy keycloak with distinct domains for internal and external users this behaviour turn into a problem.

Workarounds

To workaround that I found two options both ends with a keycloak container as below:

NoKC_HOSTNAME defined
KC_STRICT_HOSTNAME=false

That allows distinct domains for internal and external users.

Not specify `spec.hostname.hostname`

The first is to not specify spec.hostname.hostname and disable operator-managed ingress.

apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
  name: example-keycloak
  namespace: keycloak
spec:
  hostname:
    strict: false
  ingress:
    enabled: false

The trade-off is clear. The need to handle ingress creation.

Override `KC_HOSTNAME` with `spec.unsupported.podTemplate`

Yeah, this is weird but works.

Environment variables specified via podTemplate take precedence over those specified directly by the operator (I don't know whether this applies to all env vars).

apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
  name: example-keycloak
  namespace: keycloak
spec:
  hostname:
    hostname: keycloak.example.com
    strict: false
  unsupported:
    podTemplate:
      spec:
        containers:
          - env:
              - name: KC_HOSTNAME
                value: ''

The trade-off again is clear. The use of spec.unsupported is discouraged

Solution?

Perhaps the simplest solution is to instruct the operator not to set KC_HOSTNAME when spec.hostname.strict is set to false. I mean, when spec.hostname.strict is set to false operator should use spec.hostname.hostname just for create the ingress.

apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
  name: example-keycloak
  namespace: keycloak
spec:
  hostname:
    hostname: keycloak.example.com
    strict: false

Another way would be to have a spec.ingress.hostname option but I guess that will turn all more complex and error prone.

I was going to create a new issue, but I thought it would be better to create this discussion first to see more opinions.

gilvansfilho · 2026-03-31T17:09:53Z

gilvansfilho
Mar 31, 2026
Author

@shawkins would be great to have your attention on this matter

0 replies

shawkins · 2026-03-31T17:33:16Z

shawkins
Mar 31, 2026
Collaborator

Can you clarify what dynamic hostname you are looking to use?

There is already https://www.keycloak.org/operator/basic-deployment#_hostname for using a dynamic hostname, but it requires setting the ingress classname to openshift-default.

3 replies

gilvansfilho Mar 31, 2026
Author

I think you mentioned that

When running on OpenShift, with ingress enabled, and with the spec.ingress.classname set to openshift-default, you may leave the spec.hostname.hostname unpopulated in the Keycloak CR. The operator will assign a default hostname to the stored version of the CR similar to what would be created by an OpenShift Route without an explicit host - that is ingress-namespace.appsDomain If the appsDomain changes, or should you need a different hostname for any reason, then update the Keycloak CR.

Keeping spec.hostname.hostname clear and spec.ingress.classname: openshift-default give us a route with router default domain. The pod also have same INFO message:

026-03-31 18:14:04,389 INFO [org.keycloak.url.HostnameV2ProviderFactory] (main) If hostname is specified, hostname-strict is effectively ignored

This happens because under the hoods operator sets the value for spec.hostname.hostname to {keycloak-cr-name}-ingress-{namespace}.{cluster-domain} so when I apply this CR to cluster:

apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
  labels:
    app: keycloak
  name: keycloak
  namespace: rhbk
spec:
  http:
    httpEnabled: true
  proxy:
    headers: xforwarded
  hostname:
    strict: false
  ingress:
    className: openshift-default
    enabled: true

I get:

apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
  labels:
    app: keycloak
  name: keycloak
  namespace: rhbk
spec:
  http:
    httpEnabled: true
  proxy:
    headers: xforwarded
  hostname:
    hostname: keycloak-ingress-rhbk.apps-crc.testing
    strict: false
  ingress:
    className: openshift-default
    enabled: true

That way keycloak container still have a KC_HOSTNAME environment variable so we ends with strict hostname instead of dynamic hostname (when keycloak generate url's based on xforwarded or forwarded headers, like X-Forwarded-Host).

sh-5.1$ env | grep HOSTNAME
HOSTNAME=keycloak-0
KC_HOSTNAME=keycloak-ingress-rhbk.apps-crc.testing
KC_HOSTNAME_STRICT=false
sh-5.1$

The issue here is that if I need to place a load balancer in front of keycloak with a different hostname keycloak will ignore this and always generate urls with hostname equals to KC_HOSTNAME environment variable.

gilvansfilho Mar 31, 2026
Author

# Right.
gfilho@gfilho-thinkpadp1gen7:~$ curl -k -s https://keycloak-ingress-rhbk.apps-crc.testing/realms/master/.well-known/openid-configuration | jq .issuer
"https://keycloak-ingress-rhbk.apps-crc.testing/realms/master"

# Wrong. X-Forwarded-Host was ignored
# Should be "https://keycloak.gsfilho.com.br/realms/master"
gfilho@gfilho-thinkpadp1gen7:~$ curl -k -s -H 'X-Forwarded-Host: keycloak.gsfilho.com.br' https://keycloak-ingress-rhbk.apps-crc.testing/realms/master/.well-known/openid-configuration | jq .issuer
"https://keycloak-ingress-rhbk.apps-crc.testing/realms/master"

gilvansfilho Mar 31, 2026
Author

Running local without `hostname` and `hostname-strict false`

gfilho@gfilho-thinkpadp1gen7:~$ ./kc.sh start --hostname-strict false --proxy-headers xforwarded --http-enabled true
2026-03-31 15:55:20,612 INFO  [org.infinispan.CONTAINER] (main) Virtual threads support enabled
2026-03-31 15:55:21,129 INFO  [org.hibernate.orm.jdbc.batch] (JPA Startup Thread) HHH100501: Automatic JDBC statement batching enabled (maximum batch size 32)
(...)
2026-03-31 15:55:28,748 INFO  [io.quarkus] (main) Keycloak 26.4.10.redhat-00001 on JVM (powered by Quarkus 3.27.2.redhat-00001) started in 10.417s. Listening on: http://0.0.0.0:8080. Management interface listening on http://0.0.0.0:9000.
2026-03-31 15:55:28,748 INFO  [io.quarkus] (main) Profile prod activated. 
2026-03-31 15:55:28,748 INFO  [io.quarkus] (main) Installed features: [agroal, cdi, hibernate-orm, jdbc-postgresql, keycloak, micrometer, narayana-jta, opentelemetry, reactive-routes, rest, rest-jackson, smallrye-context-propagation, smallrye-health, vertx]

Curl:

gfilho@gfilho-thinkpadp1gen7:~$ curl -s http://localhost:8080/realms/master/.well-known/openid-configuration | jq .issuer
"http://localhost:8080/realms/master"

# Keycloak used X-Forwarded-Host header
gfilho@gfilho-thinkpadp1gen7:~$ curl -s -H 'X-Forwarded-Host: keycloak.internal' http://localhost:8080/realms/master/.well-known/openid-configuration | jq .issuer
"http://keycloak.internal/realms/master"

Running local with `hostname` and `hostname-strict false`

gfilho@gfilho-thinkpadp1gen7:~$ ./kc.sh start --hostname localhost --hostname-strict false --proxy-headers xforwarded --http-enabled true
2026-03-31 16:03:29,927 INFO  [org.keycloak.url.HostnameV2ProviderFactory] (main) If hostname is specified, hostname-strict is effectively ignored
2026-03-31 16:03:30,772 INFO  [org.infinispan.CONTAINER] (main) Virtual threads support enabled
2026-03-31 16:03:31,347 INFO  [org.hibernate.orm.jdbc.batch] (JPA Startup Thread) HHH100501: Automatic JDBC statement batching enabled (maximum batch size 32)
(...)
2026-03-31 16:03:32,915 INFO  [io.quarkus] (main) Keycloak 26.4.10.redhat-00001 on JVM (powered by Quarkus 3.27.2.redhat-00001) started in 4.403s. Listening on: http://0.0.0.0:8080. Management interface listening on http://0.0.0.0:9000.
2026-03-31 16:03:32,915 INFO  [io.quarkus] (main) Profile prod activated. 
2026-03-31 16:03:32,915 INFO  [io.quarkus] (main) Installed features: [agroal, cdi, hibernate-orm, jdbc-postgresql, keycloak, micrometer, narayana-jta, opentelemetry, reactive-routes, rest, rest-jackson, smallrye-context-propagation, smallrye-health, vertx]

Curl:

gfilho@gfilho-thinkpadp1gen7:~$ curl -s http://localhost:8080/realms/master/.well-known/openid-configuration | jq .issuer
"http://localhost:8080/realms/master"

# Once the hostname has been defined, the `hostname-strict` property is ignored (as per the log message), therefore the X-Forwarded-Host header is ignored.
gfilho@gfilho-thinkpadp1gen7:~$ curl -s -H 'X-Forwarded-Host: keycloak.internal' http://localhost:8080/realms/master/.well-known/openid-configuration | jq .issuer
"http://localhost/realms/master"

shawkins · 2026-03-31T19:12:31Z

shawkins
Mar 31, 2026
Collaborator

The issue here is that if I need to place a load balancer in front of keycloak with a different hostname keycloak will ignore this and always generate urls with hostname equals to KC_HOSTNAME environment variable.

Can you clarify what you mean by a different hostname? By design, there is just a single default hostname for keycloak. If your loadbalancer wants to make keycloak available as "public.domain.name", then the hostname for keycloak should be set to "public.domain.name".

If you enable dynamic backchannel requests -https://www.keycloak.org/server/hostname#_utilizing_an_internal_url_for_communication_among_clients - you must use a full url as the hostname, and then you are able to issue backchannel requests directly to the service hostname.

X-Forwarded-Host was ignored

That is the correct behavior - X-Forwarded-Host will only be used if hostname-strict=false and no hostname is set. Setting the hostname is nearly always recommended for production though.

3 replies

gilvansfilho Mar 31, 2026
Author

That is the correct behavior - X-Forwarded-Host will only be used if hostname-strict=false and no hostname is set.

That is the point. Using operator we do not have a way to configure keycloak like this.

Setting the hostname is nearly always recommended for production though.

Agree but I think we need to advice that in keycloak docs and allows user to not set hostname and set hostname-strict to false. Operator do not allow this.

shawkins Mar 31, 2026
Collaborator

To confirm - are you trying to have the keycloak instance be served as multiple front-end hostnames?

If so, is this something that could be done on a per realm basis instead (realms allow setting their frontend urls)?

And do you need tokens from one hostname to be usable by the other - because they won't be as they will have different issuers.

gilvansfilho Mar 31, 2026
Author

To confirm - are you trying to have the keycloak instance be served as multiple front-end hostnames?

Yes, is that.

If so, is this something that could be done on a per realm basis instead (realms allow setting their frontend urls)?

No. Weird but both internal and external clients are in same realm.

And do you need tokens from one hostname to be usable by the other - because they won't be as they will have different issuers.

No.

Operator: Support for create ingress / route without setting KC_HOSTNAME environment variable in application container #47564

Uh oh!

gilvansfilho Mar 28, 2026

The problem

Workarounds

Not specify spec.hostname.hostname

Override KC_HOSTNAME with spec.unsupported.podTemplate

Solution?

Replies: 3 comments · 6 replies

Uh oh!

gilvansfilho Mar 31, 2026 Author

Uh oh!

shawkins Mar 31, 2026 Collaborator

Uh oh!

Uh oh!

gilvansfilho Mar 31, 2026 Author

Uh oh!

gilvansfilho Mar 31, 2026 Author

Uh oh!

Uh oh!

gilvansfilho Mar 31, 2026 Author

Running local without hostname and hostname-strict false

Running local with hostname and hostname-strict false

Uh oh!

shawkins Mar 31, 2026 Collaborator

Uh oh!

Uh oh!

gilvansfilho Mar 31, 2026 Author

Uh oh!

Uh oh!

shawkins Mar 31, 2026 Collaborator

Uh oh!

Uh oh!

gilvansfilho Mar 31, 2026 Author

gilvansfilho
Mar 28, 2026

Not specify `spec.hostname.hostname`

Override `KC_HOSTNAME` with `spec.unsupported.podTemplate`

Replies: 3 comments 6 replies

gilvansfilho
Mar 31, 2026
Author

shawkins
Mar 31, 2026
Collaborator

gilvansfilho Mar 31, 2026
Author

gilvansfilho Mar 31, 2026
Author

gilvansfilho Mar 31, 2026
Author

Running local without `hostname` and `hostname-strict false`

Running local with `hostname` and `hostname-strict false`

shawkins
Mar 31, 2026
Collaborator

gilvansfilho Mar 31, 2026
Author

shawkins Mar 31, 2026
Collaborator

gilvansfilho Mar 31, 2026
Author