111 lines
3.7 KiB
Text
111 lines
3.7 KiB
Text
<#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 `additionalOptions` 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:
|
|
...
|
|
additionalOptions:
|
|
- 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 `additionalOptions` 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>
|