keycloak-scim/docs/guides/src/main/operator/advanced-configuration.adoc

<#import "/templates/guide.adoc" as tmpl>
<#import "/templates/kc.adoc" as kc>
<#import "/templates/options.adoc" as opts>
<#import "/templates/links.adoc" as links>

<@tmpl.guide
title="Advanced configuration"
summary="How to tune advanced aspects of the Keycloak CR">

== Advanced Configuration
In this guide, you'll learn how to configure your Keycloak deployment using advanced concepts and options provided by Custom Resources (CR).

=== Server Configuration details

Many server options are exposed as first-class citizen fields in the Keycloak CR. The structure of the CR is inspired
by the configuration structure of Keycloak itself. E.g. in order to configure `https-port` of the server, simply follow
similar pattern in the CR and use `httpsPort` field. The following example with a more complex server configuration
should give you a better picture of the relationship between server options and the Keycloak CR:

[source,yaml]
----
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 all available options please see the Keycloak CRD. For a documentation of the individual options, refer to <@links.server id="all-config"/>.

==== Additional options

Some of the expert server options are not available as dedicated fields in the Keycloak CR. Omitted are mostly fields
that require deeper understanding of underlying Keycloak implementation and/or their usability is limited in a Kubernetes
environment. Omitted are also options for providers configuration as they are dynamic based on the used provider
implementation.

The `additionalOptions` field of the Keycloak CR allows to pass to Keycloak any available configuration in the form of key-value pairs.
This allows you to specify any of the options that are omitted in the Keycloak CR.
For all the available configuration options, refer to <@links.server id="all-config"/>.

The values can be expressed as plain text strings or Kubernetes Secret references.
e.g:

[source,yaml]
----
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
----

=== Secret References

A Secret References are used by some of the dedicated options in the Keycloak CR (e.g. `tlsSecret`) or as a value in `additionalOptions`.

When specifying a Secret Reference, you have to make sure that a Secret containing the referenced keys is present in the same namespace as the CR referencing it.
Along with the Keycloak Server Deployment, the operator adds special labels to the referenced Secrets in order to watch for changes.

When a referenced Secret is modified, the operator automatically performs a rolling restart of the Keycloak Deployment to pick up the changes.

=== Unsupported features

The `unsupported` field of the CR contains highly experimental configuration options that are not completely tested and supported.

==== Pod Template

Pod Template is a raw API representation that is used for the Kubernetes Deployment Template.
This field is intended to be used as a temporary workaround if there is no officially supported field at the top level of the CR to cover your use-case.
Please consider opening an issue on GitHub to help us make the experience better.

The operator will merge the fields of the provided template with the values generated by the operator for the specific Deployment.
Using this feature, you have access to a high level of customizations, but there are no guarantees that the Deployment will work as expected.

As an example you can inject labels, annotations, or even volumes and volume mounts:

[source,yaml]
----
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
----

=== Disabling required options

By default, Keycloak and its Operator are designed to provide you with the best production-ready experience with security in mind.
Although, for development purposes, you can still disable key security features.

Specifically, you can disable the hostname and TLS as shown in the following example:

[source,yaml]
----
apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
  name: example-kc
spec:
  ...
  http:
    httpEnabled: true
  hostname:
    strict: false
    strictBackchannel: false
----

</@tmpl.guide>