Advanced Keycloak CR configuration (#11065)
* Advanced Keycloak CR configuration * Update docs/guides/src/main/operator/advanced-configuration.adoc Co-authored-by: Dominik Guhr <89905860+DGuhr@users.noreply.github.com> Co-authored-by: Dominik Guhr <89905860+DGuhr@users.noreply.github.com>
This commit is contained in:
Andrea Peruffo
GitHub
parent
854b75e132
commit
a521bcfe92
2 changed files with 131 additions and 0 deletions
111
docs/guides/src/main/operator/advanced-configuration.adoc
Normal file
111
docs/guides/src/main/operator/advanced-configuration.adoc
Normal file
|
|
@ -0,0 +1,111 @@
|
||||||
|
<#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: 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: 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: keycloak.org/v2alpha1
|
||||||
|
kind: Keycloak
|
||||||
|
metadata:
|
||||||
|
name: example-kc
|
||||||
|
spec:
|
||||||
|
...
|
||||||
|
hostname: INSECURE-DISABLE
|
||||||
|
tlsSecret: INSECURE-DISABLE
|
||||||
|
----
|
||||||
|
|
||||||
|
</@tmpl.guide>
|
||||||
|
|
@ -171,4 +171,24 @@ For debugging and development purposes we suggest you to directly connect to the
|
||||||
kubectl port-forward service/example-kc-service 8443:8443
|
kubectl port-forward service/example-kc-service 8443:8443
|
||||||
----
|
----
|
||||||
|
|
||||||
|
==== Accessing the Admin Console
|
||||||
|
|
||||||
|
When deploying Keycloak, the operator generates an arbitrary initial admin `username` and `password` and stores those credentials as a Kubernetes basic-auth Secret in the same namespace as the CR.
|
||||||
|
|
||||||
|
.Warning:
|
||||||
|
[NOTE]
|
||||||
|
Change the default admin credentials and enable MFA in Keycloak before going to production.
|
||||||
|
|
||||||
|
To fetch the initial admin credentials you have to read and decode a Kubernetes Secret.
|
||||||
|
The Secret name is derived from the Keycloak CR name plus the fixed suffix `-initial-admin`.
|
||||||
|
To get the username and password for the `example-kc` CR use the following command:
|
||||||
|
|
||||||
|
[source,bash]
|
||||||
|
----
|
||||||
|
kubectl get secret example-kc-initial-admin -o jsonpath='{.data.username}' | base64 --decode
|
||||||
|
kubectl get secret example-kc-initial-admin -o jsonpath='{.data.password}' | base64 --decode
|
||||||
|
----
|
||||||
|
|
||||||
|
You can use those credentials to access the Admin Console or the Admin REST API.
|
||||||
|
|
||||||
</@tmpl.guide>
|
</@tmpl.guide>
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue