Customizing the deployment

The deployment of Keycloak can be customized using environment settings to support different storages and other features. The central location to change to changes this is an .env file in the provision/minikube folder.

Default deployment

When running Keycloak on the minikube setup, it will as default run Keycloak with the latest nightly images of the Keycloak Operator and Keycloak with a PostgreSQL database.

See Storage configurations to see which storage options are available.

Changing the default deployment

To change the default, create an .env in the provision/minikube folder.

An example configuration as below enables PostgreSQL.

KC_DATABASE=postgres

After every change, re-run the task command to apply the changes to the minikube instance. Task will trigger the necessary scripts and will use the minimal steps to update the minikube. Running rebuild.sh is not required: It will destroy the complete instance and will take a lot longer to complete.

As an alternative way the parameters can be passed on the command line of the task command:

task KC_DATABASE="postgres"

Available Keycloak configuration options

The following configuration options are available to configure Keycloak and other parts of the system under test. All default values are configured in the Taskfile.yaml.

KC_DATABASE

Set the storage to be deployed as Keycloak’s database.

Default value: postgres

Available options:

postgres

Deploy a single-node PostgreSQL instance.

See Using PostgreSQL storage for more information.

aurora-postgres

Connect to an AWS Aurora PostgreSQL cluster.

See Using Amazon Regional Aurora PostgreSQL storage and Using Amazon Global Aurora PostgreSQL Cluster for more information.

KC_DATABASE_URL

Define the external endpoint of databases that are deployed external to the Kubernetes cluster.

Default value: empty

KC_DB_POOL_INITIAL_SIZE

Set the initial database size of the DB connection pool.

Default value: 5

For the best performance, the values for the initial, minimal and maximum DB connection pool size should all be equal. This avoids creating new DB connections when a new request comes in which is costly.

Keeping the DB connection open for as long as possible allows for server side statement caching that is bound to a connection. In the case of PostgreSQL, in order to use a server-side prepared statement, a query needs to be executed (by default) at least five times.

See the PostgreSQL docs on prepared statements for more information.

KC_DB_POOL_MAX_SIZE

Set the storage configuration parameter for Keycloak.

Default value: 10

The maximum number of DB connections multiplied by the maximum number of running Keycloak instances must not exceed the maximum number of permitted database connections for the database. The default PostgreSQL instance is configured for up to 100 DB connections.

See KC_DB_POOL_INITIAL_SIZE for additional information.

KC_DB_POOL_MIN_SIZE

Set the storage configuration parameter for Keycloak.

Default value: 5

See KC_DB_POOL_INITIAL_SIZE for more information.

KC_OPERATOR_TAG

Allows to customize the version of the Keycloak Operator.

Default value: nightly

KC_CONTAINER_IMAGE

Sets image to be used for Keycloak. When using a nightly image of the Keycloak operator, this defaults to quay.io/keycloak/keycloak:nightly.

When the image name starts with localhost/, the image will be expected to be built locally and will not be pulled from the internet.

See Using a custom Keycloak image for deployment in Kubernetes on how to build a local image.

KC_INSTANCES

Sets the number of Keycloak instances.

Default value: 1

KC_CPU_LIMITS

Sets CPU limits per Keycloak Pod.

Default value: 4

The value must adhere to the Kubernetes CPU units format.

KC_MEMORY_LIMITS_MB

Sets memory limits in MB per Keycloak Pod.

Default value: 1024

KC_METASPACE_INIT_MB

Sets the initial meta space size in MB per Keycloak JVM.

Default value: 96.

KC_METASPACE_MAX_MB

Sets the maximum meta space size in MB per Keycloak JVM.

Default value: 256.

KC_CRYOSTAT

Enable Cryostat to capture JFR recordings from Keycloak.

Default value: true.

KC_OTEL

If OpenTelemetry should be enabled for Keycloak to collect traces.

Default value: false

Available options:

  • true — enable Keycloak’s built-in OpenTelemetry tracing.

  • false — disable OpenTelemetry tracing.

KC_OTEL_SAMPLING_PERCENTAGE

How many traces should be sent to Jaeger to be reported. Only in effect if KC_OTEL is set to true.

Default value: 0.001 (0.1 % of all traces are reported to Jaeger).

While a value of 1.0 is useful to report all traces during local testing to Jaeger, it creates a lot of data which will overload the memory of the Jaeger instance, which will eventually restart. During a performance run, collect only a small percentage of all traces.

KC_CUSTOM_INFINISPAN_CONFIG

If a custom Infinispan configuration should be used. This option is valid only for the legacy store.

Default value: true

Available options:

  • true — Keycloak is configured to use a custom configuration file that is mounted to each Pod. The file can be found here: kcb-infinispan-cache-config.xml.

  • false — use the default Infinispan configuration that is part of the Keycloak distribution.

KC_HOSTNAME_OVERRIDE

Override the Keycloak hostname calculated with KC_HOSTNAME_SUFFIX. This is useful when deploying Keycloak with a domain name different to the OpenShift cluster.

Default value: ""

KC_HOSTNAME_SUFFIX

Hostname suffix used when deploying to an OpenShift environment. Use it with apps.<domain name> as shown in the URL when opening the OpenShift Console.

The default value is extracted from the console deployed on the OpenShift the user is connected to.

KC_NAMESPACE_PREFIX

By default, the Keycloak instance is deployed to the keycloak namespace. The namespace name can be customized by adding a prefix to the namespace name. The resulting namespace will be ${KC_NAMESPACE_PREFIX}keycloak.

Default value: $(whoami)-

This option is implemented only for OpenShift deployments.
KC_PORT_OFFSET

This parameter allows to change the port by some offset for each service created. This is useful when multiple Keycloak instances are deployed to the same cluster. See section Sharing cluster with multiple users for more information.

Default value: 0

Available options: 0-26

This option is implemented only for OpenShift deployments.
KC_ADMIN_PASSWORD

The password for the Keycloak admin user and Grafana admin user.

The default value is obtained from a secret from AWS Secret Manager named keycloak-master-password from region eu-central-1. If aws command fails or is not available on the machine, string admin is used.

This option is implemented only for OpenShift deployments.
KC_DISABLE_STICKY_SESSION

Running the Keycloak benchmark from a single machine makes the OpenShift Route to redirect the traffic to the same Keycloak Pod. The first connection reaches a random Keycloak Pod but future connections from the same source IP will be redirected to the Pod (sticky session). This option disables this behaviour and configure the OpenShift Route to use round-robin between all the available Keycloak Pods.

Default value: false

Available options:

  • true — Forces the OpenShift Route to use round-robin for all connection (no sticky sessions).

  • false — Uses the default OpenShift Route load-balancer rules.

This option is implemented only for OpenShift deployments.
KC_KC25_MODE

To deploy older Keycloak version prior to Keycloak 26 it is necessary to enable the KC25 mode.

Available Benchmark options

The following configuration options are available to configure the helper applications. All default values are configured in the Taskfile.yaml.

KB_RETENTION

Retention period in hours to keep logs, metrics and traces.

Default: 168h

Available options: Can be changed to any value in hours that is a multiple of 24h.

Connect to external Infinispan cluster with the Legacy Store

Only for Openshift Deployments.

If Infinispan is deployed in the Openshift cluster as described in Installing Infinispan on OpenShift, use the following variable to indicate the namespace where the Infinispan cluster is running.

KC_ISPN_NAMESPACE

The namespace in the local Openshift cluster where the Infinispan cluster is deployed.

Also, the caches need to be configured with a Remote Store. Using the Hot Rod protocol, it offloads the sessions to the Infinispan cluster. The file kcb-infinispan-cache-remote-store-config.xml contains the configuration required for this. Use KC_CUSTOM_INFINISPAN_CONFIG_FILE=config/kcb-infinispan-cache-remote-store-config.xml to upload and use this file in your Keycloak cluster.

Cross-site enabled Infinispan cluster can be used as well.