From ac73c4b28f90f634feac52630d37173a474abb6a Mon Sep 17 00:00:00 2001
From: Nicolas Bigler <nicolas.bigler@vshn.ch>
Date: Tue, 23 Jul 2024 11:34:39 +0200
Subject: [PATCH] Document custom configuration and env variables for Keycloak

Signed-off-by: Nicolas Bigler <nicolas.bigler@vshn.ch>
---
 .../vshn-managed/keycloak/customization.adoc  | 130 ++++++++++++++++++
 1 file changed, 130 insertions(+)

diff --git a/docs/modules/ROOT/pages/vshn-managed/keycloak/customization.adoc b/docs/modules/ROOT/pages/vshn-managed/keycloak/customization.adoc
index da578a0..fb34e1f 100644
--- a/docs/modules/ROOT/pages/vshn-managed/keycloak/customization.adoc
+++ b/docs/modules/ROOT/pages/vshn-managed/keycloak/customization.adoc
@@ -32,3 +32,133 @@ spec:
 <1> Container image url.
 <2> Secret name containing credentials for the registry.
 <3> Secret namespace
+
+
+== Configuration
+
+You can provide a custom configuration to Keycloak using a `ConfigMap`.
+The content of the `ConfigMap` is a JSON file based on the Keycloak export files.
+The configuration *must* be in the key `keycloak-config.json` inside the `ConfigMap`
+
+The configuration will be read during the startup of Keycloak and loaded into the database.
+
+An extensive set of configuration examples can be found https://github.com/inventage/keycloak-config-cli/tree/main/src/test/resources/import-files[here^].
+
+The configuration also supports variable substitution.
+
+Variables exposed by Spring Boot (through https://docs.spring.io/spring-boot/reference/features/external-config.html[configtree or external configuration^]) can be accessed by `$(property.name)`
+
+In additional, the string substitution support multiple prefixes for different approaches:
+
+[source]
+----
+Base64 Decoder:        $(base64Decoder:SGVsbG9Xb3JsZCE=)
+Base64 Encoder:        $(base64Encoder:HelloWorld!)
+Java Constant:         $(const:java.awt.event.KeyEvent.VK_ESCAPE)
+Date:                  $(date:yyyy-MM-dd)
+DNS:                   $(dns:address|apache.org)
+Environment Variable:  $(env:USERNAME)
+File Content:          $(file:UTF-8:src/test/resources/document.properties)
+Java:                  $(java:version)
+Localhost:             $(localhost:canonical-name)
+Properties File:       $(properties:src/test/resources/document.properties::mykey)
+Resource Bundle:       $(resourceBundle:org.example.testResourceBundleLookup:mykey)
+Script:                $(script:javascript:3 + 4)
+System Property:       $(sys:user.dir)
+URL Decoder:           $(urlDecoder:Hello%20World%21)
+URL Encoder:           $(urlEncoder:Hello World!)
+URL Content (HTTP):    $(url:UTF-8:http://www.apache.org)
+URL Content (HTTPS):   $(url:UTF-8:https://www.apache.org)
+URL Content (File):    $(url:UTF-8:file:///$(sys:user.dir)/src/test/resources/document.properties)
+XML XPath:             $(xml:src/test/resources/document.xml:/root/path/to/node)
+----
+
+=== Example
+
+The following example demonstrates how a custom configuration that creates a new realm looks like:
+
+.Configmap definition for a custom realm to be created when starting up keycloak.
+[source,yaml]
+----
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: keycloak-app1-prod-config
+  namespace: bigli-test
+data:
+  keycloak-config.json: |
+    {
+      "enabled": true,
+      "realm": "prod-app"
+    }
+----
+
+.Keycloak instance with custom configuration
+[source,yaml]
+----
+apiVersion: vshn.appcat.vshn.io/v1
+kind: VSHNKeycloak
+metadata:
+  name: keycloak-app1-prod
+  namespace: prod-app
+spec:
+  parameters:
+    service:
+      customConfigurationRef: keycloak-app1-prod-config <1>
+----
+<1> The name of the `ConfigMap`. Must be in the same namespace as the Keycloak claim.
+
+
+== Environment variables
+
+You can pass custom environment variables to your Keycloak instance. Those can then either be used by your custom providers or by your custom configuration.
+
+=== Example
+
+The following example demonstrates how a custom configuration that creates a new realm and uses environment variables looks like:
+
+.Secret containing a custom environment variable
+[source,yaml]
+----
+apiVersion: v1
+kind: Secret
+metadata:
+  name: keycloak-app2-prod-env
+  namespace: prod-app
+stringData:
+  REALM_NAME: prod-app
+type: Opaque
+----
+
+.Configmap definition referencing an environmental variable
+[source,yaml]
+----
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: keycloak-app2-prod-config
+  namespace: prod-app
+data:
+  keycloak-config.json: |
+    {
+      "enabled": true,
+      "$(env:REALM_NAME)"
+    }
+----
+
+.Keycloak instance with custom configuration and environment variables
+[source,yaml]
+----
+apiVersion: vshn.appcat.vshn.io/v1
+kind: VSHNKeycloak
+metadata:
+  name: keycloak-app2-prod
+  namespace: prod-app
+spec:
+  parameters:
+    service:
+      customConfigurationRef: keycloak-app2-prod-config <1>
+      customEnvVariablesRef: keycloak-app2-prod-env <2>
+----
+<1> The name of the `ConfigMap`. Must be in the same namespace as the Keycloak claim.
+<2> The name of the `Secret` that contains the environment variables. Must be in the same namespace as the Keycloak claim.