Keycloak.X - Helm Chart

A Helm chart for deploying the latest Quarkus based distribution of Keycloak (aka Keycloak.X or version 17+).

The chart supports using an external database, ingress, clustering and secret creation and exposes many of the Keycloak configuration variables in a more friendly and discoverable way.

Quick Start

Keycloak.X has been designed to be run from a customized image where kc.sh build has been run to tailor the configuration see the docs

See the examples folder for some example Dockerfiles. These are provided purely as reference only.

However it is possible to deploy the vanilla un-customized Keycloak image:

helm install kc ./keycloak --set 'keycloak.args=["start"]'

The admin user password will be autogenerated and placed into a secret (see Admin User below), get the password with the following command:

kubectl get secret kc-keycloak-admin -o jsonpath='{.data.password}' | base64 -d

Using port-forward to connect to Keycloak and login with the admin account:

kubectl port-forward kc-keycloak-0 8080:8080

Helm Repo

This repo on GitHub is also usable directly as a Helm public remote repo, to add this repo to helm, run the following:

helm repo add keycloak https://benc-uk.github.io/keycloak-helm
helm repo update keycloak

You can then use the chart by referencing it as keycloak/keycloak

helm install mykeycloak keycloak/keycloak ...

Chart Configuration Values

See the main chart readme for a full reference list of values that can be set. Many of these “wrap” Keycloak environmental variables.

Admin User

The values keycloak.adminUser and keycloak.adminPasswordSecret control the creation of the admin user account. If adminPasswordSecret is NOT set, then a secret will be automatically created and a random password generated. Otherwise you can use keycloak.adminPasswordSecret.name and .key to reference an existing secret you want to use, in this case the creation of this secret is done outside of this Helm chart.

Ingress

It’s generally expected that a Kubernetes ingress is put in front of Keycloak rather than exposing Keycloak directly, which is why the default proxy mode for the chart is edge this disables HTTPS and TLS on Keycloak, so that TLS can be terminated by the ingress.

See the Keycloak docs and the chart value keycloak.proxyMode setting.

The simplest configuration possible would be:

ingress:
  enabled: true
  host: keycloak.example.net

Should you wish to enable TLS, specify the secretName holding the cert (issuing of certs & TLS secrets is deemed outside the scope of this chart), e.g.

ingress:
  enabled: true
  host: keycloak.example.net
  tls:
    enabled: true
    secretName: benco-io-cert

Database Configuration

If the Keycloak image has been configured/built with database support, the runtime options for the database can be passed by the values under keycloak.database, e.g. keycloak.database.host etc

The value keycloak.database.passwordSecret is expected to stored as a key in a secret, the creation and management of this secret is outside the scope of this chart.

📃 NOTE If the image has been built with database support, and database configuration is not provided, then Keycloak defaults to certain internal parameters e.g. localhost for the database, naturally this will fail.

NOTE Only MS-SQL Server has been tested at this current time

Clustering

If the Keycloak image has been configured/built with distributed caching in order to run in a cluster, then the deployment to Kubernetes can run across multiple pods.

To enable clustering and multiple pods:

Set the replicaCount to a value greater than 1
Set keycloak.clustered to true

When keycloak.clustered is set to true two things are done by the chart:

A additional headless service is created in front of the pods, allowing for DNS discovery.
Extra parameter is passed to the Keycloak startup script, which is -Djgroups.dns.query. This is set to point at the name of the headless service.

📃 NOTE 1 If clustering (i.e. a cache stack provider) has been enabled in the Keycloak image, then keycloak.clustered must be set to true, even if the replicaCount is 1. Keycloak will fall over if dns.query is not set

📃 NOTE 2 Only the Kubernetes cache stack provider has been tested, e.g. KC_CACHE_STACK=kubernetes when running kc.sh build

Extra environmental vars and secrets

The chart is designed to pass most of the Keycloak environmental variables based on the chart values passed in, as such you don’t need to set the KC_ variables directly. However not every variable is catered for, and you may want some additional flexibility.

For this extraEnv and extraEnvSecret can be used

Example of using extraEnv would look like:

keycloak:
  extraEnv:
    KC_SOME_SETTING: "Value here"

An example of extraEnvSecret might be as follows, say you have the database username stored as a secret, in which case you would not set keycloak.database.username and instead pass it in using extraEnvSecret, as follows:

keycloak:
  extraEnvSecret:
    KC_DB_USERNAME:
      secretName: sql-database-creds
      secretKey: sql-username

URL Path

Should you wish to serve Keycloak from a different URL path, this can only be done when building the Keycloak image, e.g. KC_HTTP_RELATIVE_PATH=/foo when running kc.sh build

If this has been done, then keycloak.healthCheckPath will need to be adjusted, e.g. /foo/realms/master

Keycloak Helm Chart

Helm chart for Keycloak