<#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

The `serverConfiguration` field of the Keycloak CR allows to pass to Keycloak any available configuration in the form of key-value pairs.
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:
  ...
  serverConfiguration:
    - name: db
      value: postgres # plain text value
    - name: db-url-host
      value: postgres-db # plain text value
    - name: db-username
      secret: # Secret reference
        name: keycloak-db-secret # name of the Secret
        key: username # name of the Key in the Secret
    - name: db-password
      secret: # secret reference
        name: keycloak-db-secret # name of the Secret
        key: password # name of the Key in the Secret
----

=== Secret References

A Secret Reference can be either a value in `serverConfiguration` or the `tlsSecret`.

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 CR fields

By default, the Keycloak operator is designed to provide you with the best production-ready Deployment of Keycloak with security in mind.
Although, for development purposes, you can still disable key security features.

Specifically, you can disable the required fields with a special value `INSECURE-DISABLE`:

[source,yaml]
----
apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
  name: example-kc
spec:
  ...
  hostname: INSECURE-DISABLE
  tlsSecret: INSECURE-DISABLE
----

</@tmpl.guide>