From a521bcfe920e7d41a6d75fcc676bf0bdcabf63eb Mon Sep 17 00:00:00 2001 From: Andrea Peruffo Date: Fri, 8 Apr 2022 10:57:22 +0100 Subject: [PATCH] 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> --- .../main/operator/advanced-configuration.adoc | 111 ++++++++++++++++++ .../src/main/operator/basic-deployment.adoc | 20 ++++ 2 files changed, 131 insertions(+) create mode 100644 docs/guides/src/main/operator/advanced-configuration.adoc diff --git a/docs/guides/src/main/operator/advanced-configuration.adoc b/docs/guides/src/main/operator/advanced-configuration.adoc new file mode 100644 index 0000000000..c7b1101170 --- /dev/null +++ b/docs/guides/src/main/operator/advanced-configuration.adoc @@ -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 +---- + + diff --git a/docs/guides/src/main/operator/basic-deployment.adoc b/docs/guides/src/main/operator/basic-deployment.adoc index 1cf04b6472..8df28c4add 100644 --- a/docs/guides/src/main/operator/basic-deployment.adoc +++ b/docs/guides/src/main/operator/basic-deployment.adoc @@ -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. +