libre.sh/keycloak-scim
3
0
Fork 0
Code Issues 15 Pull requests Releases 1 Packages Activity Actions

Advanced Keycloak CR configuration (#11065)

Browse source 
* 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 2022-04-08 10:57:22 +01:00 committed by GitHub
parent 854b75e132
commit a521bcfe92
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 131 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

111
docs/guides/src/main/operator/advanced-configuration.adoc Normal file
View 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>

20
docs/guides/src/main/operator/basic-deployment.adoc
View file

@ -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
----
==== 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>