feat: implement external Keycloak support with standardized structure

michaelstingl · butonic · commit 666a57014335 · 2025-06-20T11:20:11.000+02:00
- Restructure Keycloak configuration to follow internal/external pattern per issue opencloud-eu#64 - Fix unused keycloak.external.* fields (fixes opencloud-eu#75) - Enable proper external Keycloak configuration (fixes opencloud-eu#82) - Add 'roles' to WEB_OIDC_SCOPE for proper role mapping - Update all Keycloak template references to use new structure - Update README with new configuration examples and replica warning - Bump chart version to 0.2.0 (breaking change) BREAKING CHANGE: Keycloak configuration structure changed from keycloak.* to keycloak.internal.* and keycloak.external.* Signed-off-by: Jörn Friedrich Dreyer <jfd@butonic.de>
diff --git a/charts/opencloud/Chart.yaml b/charts/opencloud/Chart.yaml
@@ -10,7 +10,7 @@ maintainers:
     email: info@opencloud.eu
     url: https://opencloud.eu
 type: application
-version: 0.1.7
+version: 0.2.0
 # renovate: datasource=docker depName=opencloudeu/opencloud-rolling
 appVersion: latest
 kubeVersion: ""
diff --git a/charts/opencloud/README.md b/charts/opencloud/README.md
@@ -275,18 +275,49 @@ This will prepend `my-registry.com/` to all image references in the chart. For e
 
 ### Keycloak Settings
 
+Keycloak configuration follows the standardized internal/external pattern (see issue #64).
+
+#### Internal Keycloak
+
+| Parameter | Description | Default |
+| --------- | ----------- | ------- |
+| `keycloak.internal.enabled` | Enable internal Keycloak deployment | `true` |
+| `keycloak.internal.image.repository` | Keycloak image repository | `quay.io/keycloak/keycloak` |
+| `keycloak.internal.image.tag` | Keycloak image tag | `26.1.4` |
+| `keycloak.internal.image.pullPolicy` | Image pull policy | `IfNotPresent` |
+| `keycloak.internal.replicas` | Number of replicas | `1` |
+| `keycloak.internal.adminUser` | Admin user | `admin` |
+| `keycloak.internal.adminPassword` | Admin password | `admin` |
+| `keycloak.internal.realm` | Realm name | `openCloud` |
+| `keycloak.internal.resources` | CPU/Memory resource requests/limits | `{}` |
+| `keycloak.internal.cors.enabled` | Enable CORS | `true` |
+| `keycloak.internal.cors.allowAllOrigins` | Allow all origins | `true` |
+
+> **Note**: When using internal Keycloak with multiple OpenCloud replicas (`opencloud.replicas > 1`), you must use an external shared database or LDAP. The embedded IDM does not support replication. See [issue #53](https://github.com/opencloud-eu/helm/issues/53) for details.
+
+#### External Keycloak
+
 | Parameter | Description | Default |
 | --------- | ----------- | ------- |
-| `keycloak.enabled` | Enable Keycloak | `true` |
-| `keycloak.replicas` | Number of replicas | `1` |
-| `keycloak.adminUser` | Admin user | `admin` |
-| `keycloak.adminPassword` | Admin password | `admin` |
-| `keycloak.resources` | CPU/Memory resource requests/limits | `{}` |
-| `keycloak.realm` | Realm name | `openCloud` |
-| `keycloak.persistence.enabled` | Enable persistence | `true` |
-| `keycloak.persistence.size` | Size of the persistent volume | `1Gi` |
-| `keycloak.persistence.storageClass` | Storage class | `""` |
-| `keycloak.persistence.accessMode` | Access mode | `ReadWriteOnce` |
+| `keycloak.external.enabled` | Enable external Keycloak | `false` |
+| `keycloak.external.url` | External Keycloak URL (without /realms/...) | `""` |
+| `keycloak.external.realm` | External Keycloak realm | `openCloud` |
+| `keycloak.external.clientId` | External Keycloak client ID | `web` |
+
+#### Example: Using External Keycloak
+
+```yaml
+keycloak:
+  internal:
+    enabled: false
+  external:
+    enabled: true
+    url: "https://keycloak.example.com"
+    realm: "my-realm"
+    clientId: "opencloud-web"
+```
+
+**Note**: Only one of `keycloak.internal.enabled` or `keycloak.external.enabled` should be set to `true`.
 
 ### PostgreSQL Settings
 
diff --git a/charts/opencloud/templates/keycloak/deployment.yaml b/charts/opencloud/templates/keycloak/deployment.yaml
@@ -1,4 +1,4 @@
-{{- if and .Values.keycloak.enabled .Values.keycloak.internal.enabled }}
+{{- if .Values.keycloak.internal.enabled }}
 apiVersion: apps/v1
 kind: Deployment
 metadata:
@@ -7,7 +7,7 @@ metadata:
     {{- include "opencloud.labels" . | nindent 4 }}
     app.kubernetes.io/component: keycloak
 spec:
-  replicas: {{ .Values.keycloak.replicas }}
+  replicas: {{ .Values.keycloak.internal.replicas }}
   selector:
     matchLabels:
       {{- include "opencloud.selectorLabels" . | nindent 6 }}
@@ -24,8 +24,8 @@ spec:
         fsGroup: 1000
       containers:
         - name: keycloak
-          image: {{ include "opencloud.image" (dict "imageValues" .Values.keycloak.image "global" .Values.global) | quote }}
-          imagePullPolicy: {{ include "opencloud.image.pullPolicy" (dict "pullPolicy" .Values.keycloak.image.pullPolicy "global" .Values.global) }}
+          image: {{ include "opencloud.image" (dict "imageValues" .Values.keycloak.internal.image "global" .Values.global) | quote }}
+          imagePullPolicy: {{ include "opencloud.image.pullPolicy" (dict "pullPolicy" .Values.keycloak.internal.image.pullPolicy "global" .Values.global) }}
           securityContext:
             allowPrivilegeEscalation: false
             capabilities:
@@ -58,29 +58,29 @@ spec:
             - name: KC_FEATURES
               value: impersonation
             - name: KEYCLOAK_ADMIN
-              value: {{ .Values.keycloak.adminUser }}
+              value: {{ .Values.keycloak.internal.adminUser }}
             - name: KEYCLOAK_ADMIN_PASSWORD
-              value: {{ .Values.keycloak.adminPassword }}
-            {{- if .Values.keycloak.cors.enabled }}
+              value: {{ .Values.keycloak.internal.adminPassword }}
+            {{- if .Values.keycloak.internal.cors.enabled }}
             - name: KC_SPI_CORS_ENABLED
               value: "true"
-            {{- if .Values.keycloak.cors.allowAllOrigins }}
+            {{- if .Values.keycloak.internal.cors.allowAllOrigins }}
             - name: KC_SPI_CORS_ORIGINS
               value: "*"
             {{- else }}
             - name: KC_SPI_CORS_ORIGINS
-              value: {{ join "," .Values.keycloak.cors.origins | quote }}
+              value: {{ join "," .Values.keycloak.internal.cors.origins | quote }}
             {{- end }}
             - name: KC_SPI_CORS_METHODS
-              value: {{ .Values.keycloak.cors.methods | quote }}
+              value: {{ .Values.keycloak.internal.cors.methods | quote }}
             - name: KC_SPI_CORS_HEADERS
-              value: {{ .Values.keycloak.cors.headers | quote }}
+              value: {{ .Values.keycloak.internal.cors.headers | quote }}
             - name: KC_SPI_CORS_EXPOSED_HEADERS
-              value: {{ .Values.keycloak.cors.exposedHeaders | quote }}
+              value: {{ .Values.keycloak.internal.cors.exposedHeaders | quote }}
             - name: KC_SPI_CORS_ALLOW_CREDENTIALS
-              value: {{ .Values.keycloak.cors.allowCredentials | quote }}
+              value: {{ .Values.keycloak.internal.cors.allowCredentials | quote }}
             - name: KC_SPI_CORS_MAX_AGE
-              value: {{ .Values.keycloak.cors.maxAge | quote }}
+              value: {{ .Values.keycloak.internal.cors.maxAge | quote }}
             {{- end }}
           ports:
             - name: http
@@ -93,7 +93,7 @@ spec:
               mountPath: /opt/keycloak/data/import-dist/opencloud-realm.json
               subPath: opencloud-realm.json
           resources:
-            {{- toYaml .Values.keycloak.resources | nindent 12 }}
+            {{- toYaml .Values.keycloak.internal.resources | nindent 12 }}
       volumes:
         - name: script
           configMap:
diff --git a/charts/opencloud/templates/keycloak/ingress.yaml b/charts/opencloud/templates/keycloak/ingress.yaml
@@ -1,4 +1,4 @@
-{{- if and .Values.ingress.enabled .Values.keycloak.enabled }}
+{{- if .Values.keycloak.internal.enabled }}
 apiVersion: networking.k8s.io/v1
 kind: Ingress
 metadata:
diff --git a/charts/opencloud/templates/keycloak/realm-configmap.yaml b/charts/opencloud/templates/keycloak/realm-configmap.yaml
@@ -1,4 +1,4 @@
-{{- if and .Values.keycloak.enabled .Values.keycloak.internal.enabled }}
+{{- if .Values.keycloak.internal.enabled }}
 apiVersion: v1
 kind: ConfigMap
 metadata:
diff --git a/charts/opencloud/templates/keycloak/script-configmap.yaml b/charts/opencloud/templates/keycloak/script-configmap.yaml
@@ -1,4 +1,4 @@
-{{- if and .Values.keycloak.enabled (not .Values.keycloak.external.enabled) }}
+{{- if .Values.keycloak.internal.enabled }}
 apiVersion: v1
 kind: ConfigMap
 metadata:
diff --git a/charts/opencloud/templates/keycloak/service.yaml b/charts/opencloud/templates/keycloak/service.yaml
@@ -1,4 +1,4 @@
-{{- if and .Values.keycloak.enabled .Values.keycloak.internal.enabled }}
+{{- if .Values.keycloak.internal.enabled }}
 apiVersion: v1
 kind: Service
 metadata:
diff --git a/charts/opencloud/templates/opencloud/deployment.yaml b/charts/opencloud/templates/opencloud/deployment.yaml
@@ -200,18 +200,26 @@ spec:
             - name: NOTIFICATIONS_SMTP_ENCRYPTION
               value: "{{ .Values.opencloud.smtp.encryption }}"
             {{- end }}
-            {{- if .Values.keycloak.enabled }}
+            {{- if or .Values.keycloak.internal.enabled .Values.keycloak.external.enabled }}
             # Keycloak IDP specific configuration
             - name: PROXY_AUTOPROVISION_ACCOUNTS
               value: "true"
             - name: PROXY_ROLE_ASSIGNMENT_DRIVER
               value: "oidc"
             - name: OC_OIDC_ISSUER
-              value: "https://{{ include "opencloud.keycloak.domain" . }}/realms/{{ .Values.keycloak.realm }}"
+              {{- if .Values.keycloak.external.enabled }}
+              value: "{{ .Values.keycloak.external.url }}/realms/{{ .Values.keycloak.external.realm }}"
+              {{- else }}
+              value: "https://{{ include "opencloud.keycloak.domain" . }}/realms/{{ .Values.keycloak.internal.realm }}"
+              {{- end }}
             - name: PROXY_OIDC_REWRITE_WELLKNOWN
               value: "true"
             - name: WEB_OIDC_CLIENT_ID
+              {{- if .Values.keycloak.external.enabled }}
+              value: "{{ .Values.keycloak.external.clientId }}"
+              {{- else }}
               value: "web"
+              {{- end }}
             - name: PROXY_USER_OIDC_CLAIM
               value: "preferred_username"
             - name: PROXY_USER_CS3_CLAIM
@@ -228,9 +236,13 @@ spec:
             - name: PROXY_OIDC_ACCESS_TOKEN_VERIFY_METHOD
               value: "jwt"
             - name: WEB_OIDC_METADATA_URL
-              value: "https://{{ include "opencloud.keycloak.domain" . }}/realms/{{ .Values.keycloak.realm }}/.well-known/openid-configuration"
+              {{- if .Values.keycloak.external.enabled }}
+              value: "{{ .Values.keycloak.external.url }}/realms/{{ .Values.keycloak.external.realm }}/.well-known/openid-configuration"
+              {{- else }}
+              value: "https://{{ include "opencloud.keycloak.domain" . }}/realms/{{ .Values.keycloak.internal.realm }}/.well-known/openid-configuration"
+              {{- end }}
             - name: WEB_OIDC_SCOPE
-              value: "openid profile email groups"
+              value: "openid profile email groups roles"
             {{- end }}
             # Admin user password
             - name: IDM_ADMIN_PASSWORD
diff --git a/charts/opencloud/templates/postgres/deployment.yaml b/charts/opencloud/templates/postgres/deployment.yaml
@@ -1,4 +1,4 @@
-{{- if and .Values.postgres.enabled .Values.keycloak.enabled }}
+{{- if and .Values.postgres.enabled .Values.keycloak.internal.enabled }}
 apiVersion: apps/v1
 kind: Deployment
 metadata:
diff --git a/charts/opencloud/templates/postgres/pvc.yaml b/charts/opencloud/templates/postgres/pvc.yaml
@@ -1,4 +1,4 @@
-{{- if and .Values.postgres.enabled .Values.keycloak.enabled .Values.postgres.persistence.enabled }}
+{{- if and .Values.postgres.enabled .Values.keycloak.internal.enabled .Values.postgres.persistence.enabled }}
 apiVersion: v1
 kind: PersistentVolumeClaim
 metadata:
diff --git a/charts/opencloud/templates/postgres/service.yaml b/charts/opencloud/templates/postgres/service.yaml
@@ -1,4 +1,4 @@
-{{- if and .Values.postgres.enabled .Values.keycloak.enabled }}
+{{- if and .Values.postgres.enabled .Values.keycloak.internal.enabled }}
 apiVersion: v1
 kind: Service
 metadata:
diff --git a/charts/opencloud/values.yaml b/charts/opencloud/values.yaml
@@ -82,70 +82,61 @@ busybox:
 # =====================================================================
 
 # Keycloak settings for identity and access management
+# Structure follows issue #64 - standardized internal/external pattern
 keycloak:
-  # Enable Keycloak
-  enabled: true
-  
-  # Keycloak image settings
-  image:
-    # Keycloak image registry
-    registry: quay.io
-    # Keycloak image repository
-    repository: keycloak/keycloak
-    # Keycloak image tag
-    tag: "26.1.4"
-    # Image pull policy
-    pullPolicy: IfNotPresent
-  
-  # Internal test Keycloak instance
+  # Internal Keycloak deployment
   internal:
-    # Enable internal test Keycloak (default: true)
+    # Enable internal Keycloak instance
     enabled: true
+    # Keycloak image settings
+    image:
+      # Keycloak image registry
+      registry: quay.io
+      # Keycloak image repository
+      repository: keycloak/keycloak
+      # Keycloak image tag
+      tag: "26.1.4"
+      # Image pull policy
+      pullPolicy: IfNotPresent
+    # Number of Keycloak replicas
+    replicas: 1
+    # Admin user
+    adminUser: admin
+    # Admin password
+    adminPassword: admin
+    # Keycloak realm
+    realm: "openCloud"
+    # CORS settings for cross-origin requests
+    cors:
+      # Enable CORS
+      enabled: true
+      # Allow all origins
+      allowAllOrigins: true
+      # Allowed origins (used if allowAllOrigins is false)
+      origins: []
+      # Allowed methods
+      methods: "GET,POST,PUT,DELETE,OPTIONS"
+      # Allowed headers
+      headers: "Origin,Accept,Authorization,Content-Type,Cache-Control"
+      # Exposed headers
+      exposedHeaders: "Access-Control-Allow-Origin,Access-Control-Allow-Credentials"
+      # Allow credentials
+      allowCredentials: "true"
+      # Max age in seconds
+      maxAge: "3600"
+    # Resources
+    resources: {}
   
-  # Use external Keycloak
+  # External Keycloak connection
   external:
     # Enable external Keycloak
     enabled: false
-    # External Keycloak URL
+    # External Keycloak URL (without /realms/...)
     url: ""
     # External Keycloak realm
     realm: "openCloud"
     # External Keycloak client ID
     clientId: "web"
-  
-  # Number of Keycloak replicas
-  replicas: 1
-  # Admin user
-  adminUser: admin
-  # Admin password
-  adminPassword: admin
-  
-  # CORS settings for cross-origin requests
-  cors:
-    # Enable CORS
-    enabled: true
-    # Allow all origins
-    allowAllOrigins: true
-    # Allowed origins (used if allowAllOrigins is false)
-    origins: []
-    # Allowed methods
-    methods: "GET,HEAD,OPTIONS,POST,PUT,DELETE"
-    # Allowed headers
-    headers: "Authorization,Content-Type,Accept,Origin,X-Requested-With"
-    # Exposed headers
-    exposedHeaders: "Content-Disposition,Content-Length,Content-Type"
-    # Allow credentials
-    allowCredentials: true
-    # Max age
-    maxAge: 3600
-  
-  # Token settings
-  token:
-    # Access token lifespan in seconds
-    accessTokenLifespan: 3600
-  
-  # Resources allocation
-  resources:
     requests:
       cpu: 100m
       memory: 256Mi

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-{{- if and .Values.ingress.enabled .Values.keycloak.enabled }}`
	`1`	`+{{- if .Values.keycloak.internal.enabled }}`
`2`	`2`	`apiVersion: networking.k8s.io/v1`
`3`	`3`	`kind: Ingress`
`4`	`4`	`metadata:`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-{{- if and .Values.keycloak.enabled .Values.keycloak.internal.enabled }}`
	`1`	`+{{- if .Values.keycloak.internal.enabled }}`
`2`	`2`	`apiVersion: v1`
`3`	`3`	`kind: ConfigMap`
`4`	`4`	`metadata:`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-{{- if and .Values.keycloak.enabled (not .Values.keycloak.external.enabled) }}`
	`1`	`+{{- if .Values.keycloak.internal.enabled }}`
`2`	`2`	`apiVersion: v1`
`3`	`3`	`kind: ConfigMap`
`4`	`4`	`metadata:`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-{{- if and .Values.postgres.enabled .Values.keycloak.enabled }}`
	`1`	`+{{- if and .Values.postgres.enabled .Values.keycloak.internal.enabled }}`
`2`	`2`	`apiVersion: apps/v1`
`3`	`3`	`kind: Deployment`
`4`	`4`	`metadata:`