Chapter 4. Advanced configuration 4.1. Advanced configuration This chapter describes how to use Custom Resources (CRs) for advanced configuration of your Red Hat build of Keycloak deployment. 4.1.1. Server configuration details Many server options are exposed as first-class citizen fields in the Keycloak CR. The structure of the CR is based on the configuration structure of Red Hat build of Keycloak. For example, to configure the https-port of the server, follow a similar pattern in the CR and use the httpsPort field. The following example is a complex server configuration; however, it illustrates the relationship between server options and the Keycloak CR: apiVersion: k8s.keycloak.org/v2alpha1 kind: Keycloak metadata: name: example-kc spec: db: vendor: postgres usernameSecret: name: usernameSecret key: usernameSecretKey passwordSecret: name: passwordSecret key: passwordSecretKey host: host database: database port: 123 schema: schema poolInitialSize: 1 poolMinSize: 2 poolMaxSize: 3 http: httpEnabled: true httpPort: 8180 httpsPort: 8543 tlsSecret: my-tls-secret hostname: hostname: my-hostname admin: my-admin-hostname strict: false strictBackchannel: false features: enabled: - docker - authorization disabled: - admin - step-up-authentication transaction: xaEnabled: false For a list of options, see the Keycloak CRD. For details on configuring options, see All configuration . 4.1.1.1. Additional options Some expert server options are unavailable as dedicated fields in the Keycloak CR. The following are examples of omitted fields: Fields that require deep understanding of the underlying Red Hat build of Keycloak implementation Fields that are not relevant to an OpenShift environment Fields for provider configuration because they are dynamic based on the used provider implementation The additionalOptions field of the Keycloak CR enables Red Hat build of Keycloak to accept any available configuration in the form of key-value pairs. You can use this field to include any option that is omitted in the Keycloak CR. For details on configuring options, see All configuration . The values can be expressed as plain text strings or Secret object references as shown in this example: apiVersion: k8s.keycloak.org/v2alpha1 kind: Keycloak metadata: name: example-kc spec: ... additionalOptions: - name: spi-connections-http-client-default-connection-pool-size secret: # Secret reference name: http-client-secret # name of the Secret key: poolSize # name of the Key in the Secret - name: spi-email-template-mycustomprovider-enabled value: true # plain text value Note The name format of options defined in this way is identical to the key format of options specified in the configuration file. For details on various configuration formats, see Configuring Red Hat build of Keycloak . 4.1.2. Secret References Secret References are used by some dedicated options in the Keycloak CR, such as tlsSecret , or as a value in additionalOptions . Similarly ConfigMap References are used by options such as the configMapFile . When specifying a Secret or ConfigMap Reference, make sure that a Secret or ConfigMap containing the referenced keys is present in the same namespace as the CR referencing it. The operator will poll approximately every minute for changes to referenced Secrets or ConfigMaps. When a meaningful change is detected, the Operator performs a rolling restart of the Red Hat build of Keycloak Deployment to pick up the changes. 4.1.3. Unsupported features The unsupported field of the CR contains highly experimental configuration options that are not completely tested and are Tech Preview. 4.1.3.1. Pod Template The Pod Template is a raw API representation that is used for the Deployment Template. This field is a temporary workaround in case no supported field exists at the top level of the CR for your use case. The Operator merges the fields of the provided template with the values generated by the Operator for the specific Deployment. With this feature, you have access to a high level of customizations. However, no guarantee exists that the Deployment will work as expected. The following example illustrates injecting labels, annotations, volumes, and volume mounts: apiVersion: k8s.keycloak.org/v2alpha1 kind: Keycloak metadata: name: example-kc spec: ... unsupported: podTemplate: metadata: labels: my-label: "keycloak" spec: containers: - volumeMounts: - name: test-volume mountPath: /mnt/test volumes: - name: test-volume secret: secretName: keycloak-additional-secret 4.1.4. Disabling required options Red Hat build of Keycloak and the Red Hat build of Keycloak Operator provide the best production-ready experience with security in mind. However, during the development phase, you can disable key security features. Specifically, you can disable the hostname and TLS as shown in the following example: apiVersion: k8s.keycloak.org/v2alpha1 kind: Keycloak metadata: name: example-kc spec: ... http: httpEnabled: true hostname: strict: false strictBackchannel: false 4.1.5. Resource requirements The Keycloak CR allows specifying the resources options for managing compute resources for the Red Hat build of Keycloak container. It provides the ability to request and limit resources independently for the main Keycloak deployment via the Keycloak CR, and for the realm import Job via the Realm Import CR. When no values are specified, the default requests memory is set to 1700MiB , and the limits memory is set to 2GiB . These values were chosen based on a deeper analysis of Red Hat build of Keycloak memory management. If no values are specified in the Realm Import CR, it falls back to the values specified in the Keycloak CR, or to the defaults as defined above. You can specify your custom values based on your requirements as follows: apiVersion: k8s.keycloak.org/v2alpha1 kind: Keycloak metadata: name: example-kc spec: ... resources: requests: cpu: 1200m memory: 896Mi limits: cpu: 6 memory: 3Gi Moreover, the Red Hat build of Keycloak container manages the heap size more effectively by providing relative values for the heap size. It is achieved by providing certain JVM options. For more details, see Running Red Hat build of Keycloak in a container . 4.1.6. Truststores If you need to provide trusted certificates, the Keycloak CR provides a top level feature for configuring the server's truststore as discussed in Configuring trusted certificates . Use the truststores stanza of the Keycloak spec to specify Secrets containing PEM encoded files, or PKCS12 files with extension .p12 or .pfx , for example: apiVersion: k8s.keycloak.org/v2alpha1 kind: Keycloak metadata: name: example-kc spec: ... truststores: my-truststore: secret: name: my-secret Where the contents of my-secret could be a PEM file, for example: apiVersion: v1 kind: Secret metadata: name: my-secret stringData: cert.pem: | -----BEGIN CERTIFICATE----- ... When running on a Kubernetes or OpenShift environment well-known locations of trusted certificates are included automatically. This includes /var/run/secrets/kubernetes.io/serviceaccount/ca.crt and the /var/run/secrets/kubernetes.io/serviceaccount/service-ca.crt when present.

Commands:
apiVersion: k8s.keycloak.org/v2alpha1 kind: Keycloak metadata: name: example-kc spec: db: vendor: postgres usernameSecret: name: usernameSecret key: usernameSecretKey passwordSecret: name: passwordSecret key: passwordSecretKey host: host database: database port: 123 schema: schema poolInitialSize: 1 poolMinSize: 2 poolMaxSize: 3 http: httpEnabled: true httpPort: 8180 httpsPort: 8543 tlsSecret: my-tls-secret hostname: hostname: my-hostname admin: my-admin-hostname strict: false strictBackchannel: false features: enabled: - docker - authorization disabled: - admin - step-up-authentication transaction: xaEnabled: false
apiVersion: k8s.keycloak.org/v2alpha1 kind: Keycloak metadata: name: example-kc spec: additionalOptions: - name: spi-connections-http-client-default-connection-pool-size secret: # Secret reference name: http-client-secret # name of the Secret key: poolSize # name of the Key in the Secret - name: spi-email-template-mycustomprovider-enabled value: true # plain text value
apiVersion: k8s.keycloak.org/v2alpha1 kind: Keycloak metadata: name: example-kc spec: unsupported: podTemplate: metadata: labels: my-label: "keycloak" spec: containers: - volumeMounts: - name: test-volume mountPath: /mnt/test volumes: - name: test-volume secret: secretName: keycloak-additional-secret
apiVersion: k8s.keycloak.org/v2alpha1 kind: Keycloak metadata: name: example-kc spec: http: httpEnabled: true hostname: strict: false strictBackchannel: false
apiVersion: k8s.keycloak.org/v2alpha1 kind: Keycloak metadata: name: example-kc spec: resources: requests: cpu: 1200m memory: 896Mi limits: cpu: 6 memory: 3Gi
apiVersion: k8s.keycloak.org/v2alpha1 kind: Keycloak metadata: name: example-kc spec: truststores: my-truststore: secret: name: my-secret
apiVersion: v1 kind: Secret metadata: name: my-secret stringData: cert.pem: | -----BEGIN CERTIFICATE-----