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>

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
+----
+
+</@tmpl.guide>

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.
+
 </@tmpl.guide>