From 956e9831bf350eb66dd25632a68bab573440ecbf Mon Sep 17 00:00:00 2001
From: Pierluigi Lenoci <pierluigi.lenoci@gmail.com>
Date: Sat, 21 Mar 2026 14:33:28 +0100
Subject: [PATCH 1/5] feat: add forceLegacyConfig flag for alphaConfig
 compatibility

- Always mount ConfigMap and pass --config flag regardless of alphaConfig
- Auto-generate minimal legacy config (email_domains only) when alphaConfig enabled
- Add config.forceLegacyConfig flag to control custom configFile behavior
- Add structured config fields: emailDomains, upstreams
- Fix configmap.yaml YAML rendering (trim markers collapsing data:/key)
- Compute checksum/config from rendered configmap for proper rollout detection
- Add comprehensive CI test scenarios and documentation

Signed-off-by: Pierluigi Lenoci <pierluigi.lenoci@gmail.com>
---
 helm/oauth2-proxy/Chart.yaml                  |  28 +++-
 ...custom-configfile-legacy-false-values.yaml |  21 +++
 ...-custom-configfile-legacy-true-values.yaml |  21 +++
 .../ci/alphaconfig-legacy-false-values.yaml   |  19 +++
 .../ci/alphaconfig-legacy-true-values.yaml    |  19 +++
 .../ci/custom-configfile-values.yaml          |   9 ++
 .../ci/existing-configmap-values.yaml         |  16 +++
 helm/oauth2-proxy/templates/configmap.yaml    |   8 +-
 helm/oauth2-proxy/templates/deployment.yaml   |  10 +-
 helm/oauth2-proxy/values.yaml                 | 125 +++++++++++++++++-
 10 files changed, 257 insertions(+), 19 deletions(-)
 create mode 100644 helm/oauth2-proxy/ci/alphaconfig-custom-configfile-legacy-false-values.yaml
 create mode 100644 helm/oauth2-proxy/ci/alphaconfig-custom-configfile-legacy-true-values.yaml
 create mode 100644 helm/oauth2-proxy/ci/alphaconfig-legacy-false-values.yaml
 create mode 100644 helm/oauth2-proxy/ci/alphaconfig-legacy-true-values.yaml
 create mode 100644 helm/oauth2-proxy/ci/custom-configfile-values.yaml
 create mode 100644 helm/oauth2-proxy/ci/existing-configmap-values.yaml

diff --git a/helm/oauth2-proxy/Chart.yaml b/helm/oauth2-proxy/Chart.yaml
index bc800656..5577b2c1 100644
--- a/helm/oauth2-proxy/Chart.yaml
+++ b/helm/oauth2-proxy/Chart.yaml
@@ -1,5 +1,5 @@
 name: oauth2-proxy
-version: 10.2.0
+version: 10.3.0
 apiVersion: v2
 appVersion: 7.15.0
 home: https://oauth2-proxy.github.io/oauth2-proxy/
@@ -30,8 +30,28 @@ maintainers:
 kubeVersion: ">=1.16.0-0"
 annotations:
   artifacthub.io/changes: |
+    - kind: fixed
+      description: Restructured config.configFile generation to support alphaConfig without conflicts
+      links:
+        - name: GitHub Issue
+          url: https://github.com/oauth2-proxy/manifests/issues/226
+    - kind: added
+      description: Added structured configuration with config.emailDomains and config.upstreams for better flexibility
+      links:
+        - name: GitHub Issue
+          url: https://github.com/oauth2-proxy/manifests/issues/226
+    - kind: added
+      description: Added config.forceLegacyConfig flag for users with custom configFile when using alphaConfig
+      links:
+        - name: GitHub Issue
+          url: https://github.com/oauth2-proxy/manifests/issues/226
+    - kind: added
+      description: Added comprehensive alphaConfig examples with upstreamConfig configuration
+      links:
+        - name: GitHub Issue
+          url: https://github.com/oauth2-proxy/manifests/issues/311
     - kind: added
-      description: feat: full support for ParentRef fields of gateway-api HTTPRoutes
+      description: Documented external secrets usage with alphaConfig via extraEnv (Azure Key Vault CSI Driver example)
       links:
-        - name: GitHub PR
-          url: https://github.com/oauth2-proxy/manifests/pull/391
+        - name: GitHub Issue
+          url: https://github.com/oauth2-proxy/manifests/issues/302
diff --git a/helm/oauth2-proxy/ci/alphaconfig-custom-configfile-legacy-false-values.yaml b/helm/oauth2-proxy/ci/alphaconfig-custom-configfile-legacy-false-values.yaml
new file mode 100644
index 00000000..bc84fb77
--- /dev/null
+++ b/helm/oauth2-proxy/ci/alphaconfig-custom-configfile-legacy-false-values.yaml
@@ -0,0 +1,21 @@
+# Test Case 6: alphaConfig enabled + custom configFile + forceLegacyConfig=false
+# Expected: ConfigMap with ONLY email_domains (ignores custom configFile)
+
+alphaConfig:
+  enabled: true
+  configData:
+    providers:
+      - id: google
+        provider: google
+        clientID: fake-client-id
+        clientSecret: fake-client-secret
+    upstreamConfig:
+      upstreams:
+        - id: alpha-service
+          path: /
+          uri: http://alpha-backend:8080
+
+config:
+  configFile: |-
+    email_domains = [ "example.com" ]
+  forceLegacyConfig: false
diff --git a/helm/oauth2-proxy/ci/alphaconfig-custom-configfile-legacy-true-values.yaml b/helm/oauth2-proxy/ci/alphaconfig-custom-configfile-legacy-true-values.yaml
new file mode 100644
index 00000000..f86b22ff
--- /dev/null
+++ b/helm/oauth2-proxy/ci/alphaconfig-custom-configfile-legacy-true-values.yaml
@@ -0,0 +1,21 @@
+# Test Case 5: alphaConfig enabled + custom configFile + forceLegacyConfig=true
+# Expected: ConfigMap with custom configFile content (backward compatible)
+
+alphaConfig:
+  enabled: true
+  configData:
+    providers:
+      - id: google
+        provider: google
+        clientID: fake-client-id
+        clientSecret: fake-client-secret
+    upstreamConfig:
+      upstreams:
+        - id: alpha-service
+          path: /
+          uri: http://alpha-backend:8080
+
+config:
+  configFile: |-
+    email_domains = [ "example.com" ]
+  forceLegacyConfig: true
diff --git a/helm/oauth2-proxy/ci/alphaconfig-legacy-false-values.yaml b/helm/oauth2-proxy/ci/alphaconfig-legacy-false-values.yaml
new file mode 100644
index 00000000..99db3dfd
--- /dev/null
+++ b/helm/oauth2-proxy/ci/alphaconfig-legacy-false-values.yaml
@@ -0,0 +1,19 @@
+# Test Case 4: alphaConfig enabled with forceLegacyConfig=false
+# Expected: ConfigMap with ONLY email_domains (no upstreams) - FIX for issue #226
+
+alphaConfig:
+  enabled: true
+  configData:
+    providers:
+      - id: google
+        provider: google
+        clientID: fake-client-id
+        clientSecret: fake-client-secret
+    upstreamConfig:
+      upstreams:
+        - id: alpha-service
+          path: /
+          uri: http://alpha-backend:8080
+
+config:
+  forceLegacyConfig: false
diff --git a/helm/oauth2-proxy/ci/alphaconfig-legacy-true-values.yaml b/helm/oauth2-proxy/ci/alphaconfig-legacy-true-values.yaml
new file mode 100644
index 00000000..b3cf6537
--- /dev/null
+++ b/helm/oauth2-proxy/ci/alphaconfig-legacy-true-values.yaml
@@ -0,0 +1,19 @@
+# Test Case 3: alphaConfig enabled with forceLegacyConfig=true (default)
+# Expected: legacy ConfigMap containing only email_domains (upstreams omitted)
+
+alphaConfig:
+  enabled: true
+  configData:
+    providers:
+      - id: google
+        provider: google
+        clientID: fake-client-id
+        clientSecret: fake-client-secret
+    upstreamConfig:
+      upstreams:
+        - id: alpha-service
+          path: /
+          uri: http://alpha-backend:8080
+
+config:
+  forceLegacyConfig: true
diff --git a/helm/oauth2-proxy/ci/custom-configfile-values.yaml b/helm/oauth2-proxy/ci/custom-configfile-values.yaml
new file mode 100644
index 00000000..2db37929
--- /dev/null
+++ b/helm/oauth2-proxy/ci/custom-configfile-values.yaml
@@ -0,0 +1,9 @@
+# Test Case 2: Custom configFile (alphaConfig disabled)
+# Expected: ConfigMap with custom configFile content
+
+config:
+  configFile: |-
+    email_domains = [ "example.com" ]
+    upstreams = [ "http://backend:8080" ]
+    pass_basic_auth = false
+    pass_access_token = true
diff --git a/helm/oauth2-proxy/ci/existing-configmap-values.yaml b/helm/oauth2-proxy/ci/existing-configmap-values.yaml
new file mode 100644
index 00000000..f00c1b57
--- /dev/null
+++ b/helm/oauth2-proxy/ci/existing-configmap-values.yaml
@@ -0,0 +1,16 @@
+# Test Case 7: Using an existing external ConfigMap
+# Expected: Chart does NOT generate ConfigMap, uses the external one provided via extraObjects
+
+config:
+  existingConfig: "my-external-configmap"
+
+# Create the external ConfigMap that the chart expects
+extraObjects:
+  - apiVersion: v1
+    kind: ConfigMap
+    metadata:
+      name: my-external-configmap
+    data:
+      oauth2_proxy.cfg: |
+        email_domains = [ "*" ]
+        upstreams = [ "file:///dev/null" ]
diff --git a/helm/oauth2-proxy/templates/configmap.yaml b/helm/oauth2-proxy/templates/configmap.yaml
index 0f164d23..96e4c93d 100644
--- a/helm/oauth2-proxy/templates/configmap.yaml
+++ b/helm/oauth2-proxy/templates/configmap.yaml
@@ -1,5 +1,4 @@
 {{- if not .Values.config.existingConfig }}
-{{- if .Values.config.configFile }}
 apiVersion: v1
 kind: ConfigMap
 metadata:
@@ -13,6 +12,11 @@ metadata:
   name: {{ template "oauth2-proxy.fullname" . }}
   namespace: {{ template "oauth2-proxy.namespace" $ }}
 data:
+  {{- if and .Values.config.configFile (or (not .Values.alphaConfig.enabled) .Values.config.forceLegacyConfig) }}
   oauth2_proxy.cfg: {{ tpl .Values.config.configFile $ | quote }}
-{{- end }}
+  {{- else if .Values.alphaConfig.enabled }}
+  oauth2_proxy.cfg: {{ printf "email_domains = %s" (.Values.config.emailDomains | toJson) | quote }}
+  {{- else }}
+  oauth2_proxy.cfg: {{ printf "email_domains = %s\nupstreams = %s" (.Values.config.emailDomains | toJson) (.Values.config.upstreams | toJson) | quote }}
+  {{- end }}
 {{- end }}
diff --git a/helm/oauth2-proxy/templates/deployment.yaml b/helm/oauth2-proxy/templates/deployment.yaml
index f5f5b4dd..a9341dad 100644
--- a/helm/oauth2-proxy/templates/deployment.yaml
+++ b/helm/oauth2-proxy/templates/deployment.yaml
@@ -27,8 +27,8 @@ spec:
   template:
     metadata:
       annotations:
-        {{- if .Values.config.configFile }}
-        checksum/config: {{ tpl .Values.config.configFile $ | sha256sum }}
+        {{- if not .Values.config.existingConfig }}
+        checksum/config: {{ include (print $.Template.BasePath "/configmap.yaml") . | sha256sum }}
         {{- end }}
         {{- if .Values.alphaConfig.enabled }}
         checksum/alpha-config: {{ include "oauth2-proxy.alpha-config" . | sha256sum }}
@@ -145,9 +145,7 @@ spec:
             {{- toYaml . | nindent 10 }}
           {{- end }}
         {{- end }}
-        {{- if or .Values.config.existingConfig .Values.config.configFile }}
           - --config=/etc/oauth2_proxy/oauth2_proxy.cfg
-        {{- end }}
         {{- if .Values.authenticatedEmailsFile.enabled }}
         {{- if .Values.authenticatedEmailsFile.template }}
           - --authenticated-emails-file=/etc/oauth2-proxy/{{ .Values.authenticatedEmailsFile.template }}
@@ -304,11 +302,9 @@ spec:
           readOnly: true
 {{- end }}
 {{- end }}
-{{- if or .Values.config.existingConfig .Values.config.configFile }}
         - mountPath: /etc/oauth2_proxy/oauth2_proxy.cfg
           name: configmain
           subPath: oauth2_proxy.cfg
-{{- end }}
 {{- if .Values.alphaConfig.enabled }}
         - mountPath: /etc/oauth2_proxy/oauth2_proxy.yml
           name: configalpha
@@ -372,12 +368,10 @@ spec:
           name: {{ template "oauth2-proxy.fullname" . }}-wait-for-redis
           defaultMode: 0775
 {{- end }}
-{{- if or .Values.config.existingConfig .Values.config.configFile }}
       - configMap:
           defaultMode: 420
           name: {{ if .Values.config.existingConfig }}{{ .Values.config.existingConfig }}{{ else }}{{ template "oauth2-proxy.fullname" . }}{{ end }}
         name: configmain
-{{- end }}
 {{- if .Values.alphaConfig.enabled }}
 {{- if .Values.alphaConfig.existingConfig }}
       - configMap:
diff --git a/helm/oauth2-proxy/values.yaml b/helm/oauth2-proxy/values.yaml
index e2538b0e..4590da3b 100644
--- a/helm/oauth2-proxy/values.yaml
+++ b/helm/oauth2-proxy/values.yaml
@@ -55,12 +55,65 @@ config:
     # Example:
     #  - group1@example.com
     #  - group2@example.com
-  # Default configuration, to be overridden
-  configFile: |-
-    email_domains = [ "*" ]
-    upstreams = [ "file:///dev/null" ]
-  # Custom configuration file: oauth2_proxy.cfg
+  #
+  # Configuration file generation / precedence
+  # 1. If config.existingConfig is set, that external ConfigMap is used
+  #    and no chart-managed ConfigMap is generated. configFile,
+  #    emailDomains and upstreams are all ignored.
+  # 2. If configFile is set, it takes precedence over the structured
+  #    config below (except when alphaConfig.enabled=true and
+  #    forceLegacyConfig=false, in which case configFile is ignored).
+  # 3. If configFile is empty/not set, the config is auto-generated
+  #    from emailDomains and upstreams.
+  configFile: ""
+  # Email domains allowed to authenticate (used when configFile is
+  # empty)
+  emailDomains: ["*"]
+  # Legacy upstream configuration (used when configFile is empty
+  # and alphaConfig is disabled)
+  # When alphaConfig.enabled is true, define upstreams in
+  # alphaConfig.configData.upstreamConfig instead
+  upstreams: ["file:///dev/null"]
+  # Behavior when using alphaConfig together with a custom config file
+  #
+  # This flag only has an effect when:
+  #   - alphaConfig.enabled is true, AND
+  #   - you provide a custom config.configFile.
+  #
+  # Auto-generated config when alphaConfig.enabled=true is always a
+  # minimal legacy config (no upstreams), regardless of this flag.
+  #
+  # When true (default): Honor a custom configFile
+  # even when alphaConfig.enabled=true. If your custom config still
+  # contains deprecated options (for example 'upstreams'),
+  # oauth2-proxy may fail with:
+  #   "failed to load core options: '' has invalid keys: upstreams"
+  #
+  # When false: Ignore any custom configFile when
+  # alphaConfig.enabled=true and instead generate the minimal
+  # legacy config. This preserves compatibility and avoids
+  # invalid legacy options such as 'upstreams'.
+  #
+  # If you are using alphaConfig and see the error:
+  # "failed to load core options: '' has invalid keys: upstreams"
+  # you have two options:
+  # 1) Keep forceLegacyConfig: true (default):
+  #    - Continue using your custom legacy config, but ensure it
+  #      is alpha-compatible (remove 'upstreams' and any other
+  #      keys no longer supported).
+  # 2) Set forceLegacyConfig: false:
+  #    - The chart will ignore config.configFile for alphaConfig.
+  #    - Define upstreams in alphaConfig.configData.upstreamConfig
+  #      instead (see examples below).
+  #    - Move any other relevant settings into alphaConfig and/or
+  #      flags rather than relying on a custom legacy configFile.
+  forceLegacyConfig: true
+  #
+  # Custom configuration file: oauth2_proxy.cfg (overrides
+  # emailDomains and upstreams)
+  # Example:
   # configFile: |-
+  #   email_domains = [ "*" ]
   #   pass_basic_auth = false
   #   pass_access_token = true
   # Use an existing config map (see configmap.yaml for required fields)
@@ -77,6 +130,33 @@ alphaConfig:
   metricsConfigData: {}
   # Arbitrary configuration data to append
   configData: {}
+  #
+  # Example: Multiple upstreams with path-based routing
+  # configData:
+  #   upstreamConfig:
+  #     upstreams:
+  #       - id: service1
+  #         path: /
+  #         uri: http://service1:8080
+  #         flushInterval: 1s
+  #         passHostHeader: true
+  #         proxyWebSockets: true
+  #       - id: service2
+  #         path: /api/
+  #         uri: http://service2:8081
+  #         rewriteTarget: /v1/
+  #         injectResponseHeaders:
+  #           - name: X-Custom-Header
+  #             values:
+  #               - value: custom-value
+  #   injectResponseHeaders:
+  #     - name: X-Auth-Request-Email
+  #       values:
+  #         - claim: email
+  #
+  # For more information on alpha config options, see:
+  # https://oauth2-proxy.github.io/oauth2-proxy/configuration/alpha-config
+  #
   # Arbitrary configuration to append
   # This is treated as a Go template and rendered with the root context
   configFile: ""
@@ -84,6 +164,23 @@ alphaConfig:
   existingConfig: ~
   # Use an existing secret
   existingSecret: ~
+  #
+  # NOTE: When using alphaConfig with external secrets (e.g., Azure
+  # Key Vault CSI Driver), you can inject secrets via the top-level
+  # extraEnv (see the extraEnv section below) instead of embedding
+  # them in the config:
+  #
+  # extraEnv:
+  #   - name: OAUTH2_PROXY_CLIENT_ID
+  #     valueFrom:
+  #       secretKeyRef:
+  #         name: external-secret
+  #         key: client-id
+  #   - name: OAUTH2_PROXY_CLIENT_SECRET
+  #     valueFrom:
+  #       secretKeyRef:
+  #         name: external-secret
+  #         key: client-secret
 
 image:
   registry: ""
@@ -106,6 +203,24 @@ imagePullSecrets: []
 
 extraArgs: {}
 extraEnv: []
+# Example: Load secrets from an external secret (e.g., Azure Key
+# Vault via CSI Driver)
+# extraEnv:
+#   - name: OAUTH2_PROXY_CLIENT_ID
+#     valueFrom:
+#       secretKeyRef:
+#         name: azure-keyvault-secret
+#         key: client-id
+#   - name: OAUTH2_PROXY_CLIENT_SECRET
+#     valueFrom:
+#       secretKeyRef:
+#         name: azure-keyvault-secret
+#         key: client-secret
+#   - name: OAUTH2_PROXY_COOKIE_SECRET
+#     valueFrom:
+#       secretKeyRef:
+#         name: azure-keyvault-secret
+#         key: cookie-secret
 
 envFrom: []
 # Load environment variables from a ConfigMap(s) and/or Secret(s)

From 88c0ce68b6a4a4c910e5ccdf7d2739b394d35efd Mon Sep 17 00:00:00 2001
From: Jan Larwig <jan@larwig.com>
Date: Sun, 22 Mar 2026 19:02:31 +0100
Subject: [PATCH 2/5] test(ci): update test case files for config testing

Signed-off-by: Jan Larwig <jan@larwig.com>
---
 .../ci/alphaconfig-1-legacy-true-values.yaml  | 20 +++++++++++++
 .../ci/alphaconfig-2-legacy-false-values.yaml | 19 ++++++++++++
 ...-custom-configfile-legacy-true-values.yaml | 22 ++++++++++++++
 ...custom-configfile-legacy-false-values.yaml | 22 ++++++++++++++
 ...xisting-configmap-legacy-false-values.yaml | 30 +++++++++++++++++++
 ...existing-configmap-legacy-true-values.yaml | 30 +++++++++++++++++++
 .../ci/existing-configmap-values.yaml         |  3 --
 7 files changed, 143 insertions(+), 3 deletions(-)
 create mode 100644 helm/oauth2-proxy/ci/alphaconfig-1-legacy-true-values.yaml
 create mode 100644 helm/oauth2-proxy/ci/alphaconfig-2-legacy-false-values.yaml
 create mode 100644 helm/oauth2-proxy/ci/alphaconfig-3-custom-configfile-legacy-true-values.yaml
 create mode 100644 helm/oauth2-proxy/ci/alphaconfig-4-custom-configfile-legacy-false-values.yaml
 create mode 100644 helm/oauth2-proxy/ci/alphaconfig-5-existing-configmap-legacy-false-values.yaml
 create mode 100644 helm/oauth2-proxy/ci/alphaconfig-6-existing-configmap-legacy-true-values.yaml

diff --git a/helm/oauth2-proxy/ci/alphaconfig-1-legacy-true-values.yaml b/helm/oauth2-proxy/ci/alphaconfig-1-legacy-true-values.yaml
new file mode 100644
index 00000000..fd40dfc6
--- /dev/null
+++ b/helm/oauth2-proxy/ci/alphaconfig-1-legacy-true-values.yaml
@@ -0,0 +1,20 @@
+# Test Case 1: alphaConfig enabled with no custom legacy config
+# Expected: Default behavior still generates the minimal legacy config with only email_domains.
+
+alphaConfig:
+  enabled: true
+  configData:
+    providers:
+      - id: google
+        provider: google
+        clientID: fake-client-id
+        clientSecret: fake-client-secret
+    upstreamConfig:
+      upstreams:
+        - id: alpha-service
+          path: /
+          uri: http://alpha-backend:8080
+
+# Implicit through default values, but explicitly set here for clarity in the test case
+config:
+  forceLegacyConfig: true
\ No newline at end of file
diff --git a/helm/oauth2-proxy/ci/alphaconfig-2-legacy-false-values.yaml b/helm/oauth2-proxy/ci/alphaconfig-2-legacy-false-values.yaml
new file mode 100644
index 00000000..405a72c0
--- /dev/null
+++ b/helm/oauth2-proxy/ci/alphaconfig-2-legacy-false-values.yaml
@@ -0,0 +1,19 @@
+# Test Case 2: alphaConfig enabled with forceLegacyConfig=false and no custom legacy config
+# Expected: Chart generates the minimal legacy config with only email_domains.
+
+alphaConfig:
+  enabled: true
+  configData:
+    providers:
+      - id: google
+        provider: google
+        clientID: fake-client-id
+        clientSecret: fake-client-secret
+    upstreamConfig:
+      upstreams:
+        - id: alpha-service
+          path: /
+          uri: http://alpha-backend:8080
+
+config:
+  forceLegacyConfig: false
diff --git a/helm/oauth2-proxy/ci/alphaconfig-3-custom-configfile-legacy-true-values.yaml b/helm/oauth2-proxy/ci/alphaconfig-3-custom-configfile-legacy-true-values.yaml
new file mode 100644
index 00000000..8dd2786c
--- /dev/null
+++ b/helm/oauth2-proxy/ci/alphaconfig-3-custom-configfile-legacy-true-values.yaml
@@ -0,0 +1,22 @@
+# Test Case 3: alphaConfig enabled + custom configFile + forceLegacyConfig=true
+# Expected: Chart keeps the custom legacy config file content unchanged.
+
+alphaConfig:
+  enabled: true
+  configData:
+    providers:
+      - id: google
+        provider: google
+        clientID: fake-client-id
+        clientSecret: fake-client-secret
+    upstreamConfig:
+      upstreams:
+        - id: alpha-service
+          path: /
+          uri: http://alpha-backend:8080
+
+config:
+  configFile: |-
+    email_domains = [ "example.com" ]
+    pass_access_token = true
+  forceLegacyConfig: true
diff --git a/helm/oauth2-proxy/ci/alphaconfig-4-custom-configfile-legacy-false-values.yaml b/helm/oauth2-proxy/ci/alphaconfig-4-custom-configfile-legacy-false-values.yaml
new file mode 100644
index 00000000..55475297
--- /dev/null
+++ b/helm/oauth2-proxy/ci/alphaconfig-4-custom-configfile-legacy-false-values.yaml
@@ -0,0 +1,22 @@
+# Test Case 4: alphaConfig enabled + custom configFile + forceLegacyConfig=false
+# Expected: Chart ignores the custom legacy config and generates only email_domains.
+
+alphaConfig:
+  enabled: true
+  configData:
+    providers:
+      - id: google
+        provider: google
+        clientID: fake-client-id
+        clientSecret: fake-client-secret
+    upstreamConfig:
+      upstreams:
+        - id: alpha-service
+          path: /
+          uri: http://alpha-backend:8080
+
+config:
+  configFile: |-
+    email_domains = [ "example.com" ]
+    upstreams = [ "http://ignored-backend:8080" ]
+  forceLegacyConfig: false
diff --git a/helm/oauth2-proxy/ci/alphaconfig-5-existing-configmap-legacy-false-values.yaml b/helm/oauth2-proxy/ci/alphaconfig-5-existing-configmap-legacy-false-values.yaml
new file mode 100644
index 00000000..e0e0e16c
--- /dev/null
+++ b/helm/oauth2-proxy/ci/alphaconfig-5-existing-configmap-legacy-false-values.yaml
@@ -0,0 +1,30 @@
+# Test Case 5: alphaConfig enabled + existingConfig + forceLegacyConfig=false
+# Expected: Chart ignores the external legacy ConfigMap and generates only email_domains.
+
+alphaConfig:
+  enabled: true
+  configData:
+    providers:
+      - id: google
+        provider: google
+        clientID: fake-client-id
+        clientSecret: fake-client-secret
+    upstreamConfig:
+      upstreams:
+        - id: alpha-service
+          path: /
+          uri: http://alpha-backend:8080
+
+config:
+  existingConfig: my-external-configmap
+  forceLegacyConfig: false
+
+extraObjects:
+  - apiVersion: v1
+    kind: ConfigMap
+    metadata:
+      name: my-external-configmap
+    data:
+      oauth2_proxy.cfg: |
+        email_domains = [ "ignored.example.com" ]
+        upstreams = [ "http://ignored-backend:8080" ]
\ No newline at end of file
diff --git a/helm/oauth2-proxy/ci/alphaconfig-6-existing-configmap-legacy-true-values.yaml b/helm/oauth2-proxy/ci/alphaconfig-6-existing-configmap-legacy-true-values.yaml
new file mode 100644
index 00000000..c1372470
--- /dev/null
+++ b/helm/oauth2-proxy/ci/alphaconfig-6-existing-configmap-legacy-true-values.yaml
@@ -0,0 +1,30 @@
+# Test Case 6: alphaConfig enabled + existingConfig + forceLegacyConfig=true
+# Expected: Chart mounts the external legacy ConfigMap as the main config.
+
+alphaConfig:
+  enabled: true
+  configData:
+    providers:
+      - id: google
+        provider: google
+        clientID: fake-client-id
+        clientSecret: fake-client-secret
+    upstreamConfig:
+      upstreams:
+        - id: alpha-service
+          path: /
+          uri: http://alpha-backend:8080
+
+config:
+  existingConfig: my-external-configmap
+  forceLegacyConfig: true
+
+extraObjects:
+  - apiVersion: v1
+    kind: ConfigMap
+    metadata:
+      name: my-external-configmap
+    data:
+      oauth2_proxy.cfg: |
+        email_domains = [ "legacy.example.com" ]
+        pass_access_token = true
\ No newline at end of file
diff --git a/helm/oauth2-proxy/ci/existing-configmap-values.yaml b/helm/oauth2-proxy/ci/existing-configmap-values.yaml
index f00c1b57..ba219a46 100644
--- a/helm/oauth2-proxy/ci/existing-configmap-values.yaml
+++ b/helm/oauth2-proxy/ci/existing-configmap-values.yaml
@@ -1,6 +1,3 @@
-# Test Case 7: Using an existing external ConfigMap
-# Expected: Chart does NOT generate ConfigMap, uses the external one provided via extraObjects
-
 config:
   existingConfig: "my-external-configmap"
 

From de9be5fd428f7d57ccccc48bada4c15e2bcddc60 Mon Sep 17 00:00:00 2001
From: Jan Larwig <jan@larwig.com>
Date: Sun, 22 Mar 2026 19:16:14 +0100
Subject: [PATCH 3/5] feat(alpha-config): rework forceLegacyConfig flag

* Refactored config logic into helpers (_helpers.tpl): Moved inline conditionals from configmap.yaml into reusable templates (legacy-config.mode, legacy-config.name, legacy-config.content) for better and more central maintainability

* Fixed checksum behavior: Changed deployment annotation to hash actual rendered config content instead of the template file path (this should ensure that pods actually roll when values change, not just when templates change)

* Renamed the CI coverage: 6 granular test cases covering all combinations of alphaConfig.enabled + forceLegacyConfig + existingConfig/configFile

* Updated the alphaConfig migration guide and precedence rules in Readme and other places like the values yaml and helpers

Signed-off-by: Jan Larwig <jan@larwig.com>
---
 helm/oauth2-proxy/Chart.yaml                  |  5 ---
 helm/oauth2-proxy/README.md                   | 26 +++++++++---
 .../ci/alphaconfig-1-legacy-true-values.yaml  |  2 +-
 ...-custom-configfile-legacy-true-values.yaml |  2 +-
 ...xisting-configmap-legacy-false-values.yaml |  2 +-
 ...existing-configmap-legacy-true-values.yaml |  2 +-
 ...custom-configfile-legacy-false-values.yaml | 21 ----------
 ...-custom-configfile-legacy-true-values.yaml | 21 ----------
 .../ci/alphaconfig-legacy-false-values.yaml   | 19 ---------
 .../ci/alphaconfig-legacy-true-values.yaml    | 19 ---------
 .../ci/custom-configfile-values.yaml          |  9 ----
 helm/oauth2-proxy/templates/_helpers.tpl      | 38 +++++++++++++++++
 helm/oauth2-proxy/templates/configmap.yaml    | 11 ++---
 helm/oauth2-proxy/templates/deployment.yaml   |  6 +--
 helm/oauth2-proxy/values.yaml                 | 41 +++++++++++--------
 15 files changed, 92 insertions(+), 132 deletions(-)
 delete mode 100644 helm/oauth2-proxy/ci/alphaconfig-custom-configfile-legacy-false-values.yaml
 delete mode 100644 helm/oauth2-proxy/ci/alphaconfig-custom-configfile-legacy-true-values.yaml
 delete mode 100644 helm/oauth2-proxy/ci/alphaconfig-legacy-false-values.yaml
 delete mode 100644 helm/oauth2-proxy/ci/alphaconfig-legacy-true-values.yaml
 delete mode 100644 helm/oauth2-proxy/ci/custom-configfile-values.yaml

diff --git a/helm/oauth2-proxy/Chart.yaml b/helm/oauth2-proxy/Chart.yaml
index 5577b2c1..a051e4cc 100644
--- a/helm/oauth2-proxy/Chart.yaml
+++ b/helm/oauth2-proxy/Chart.yaml
@@ -50,8 +50,3 @@ annotations:
       links:
         - name: GitHub Issue
           url: https://github.com/oauth2-proxy/manifests/issues/311
-    - kind: added
-      description: Documented external secrets usage with alphaConfig via extraEnv (Azure Key Vault CSI Driver example)
-      links:
-        - name: GitHub Issue
-          url: https://github.com/oauth2-proxy/manifests/issues/302
diff --git a/helm/oauth2-proxy/README.md b/helm/oauth2-proxy/README.md
index 720e15ba..b7cd10b1 100644
--- a/helm/oauth2-proxy/README.md
+++ b/helm/oauth2-proxy/README.md
@@ -148,7 +148,7 @@ With above new chart version won't add extra `-ha` suffix to all redis resources
 The following table lists the configurable parameters of the oauth2-proxy chart and their default values.
 
 | Parameter                                             | Description                                                                                                                                                                                                                                                      | Default                                                                                              |
-|-------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------|
+|-------------------------------------------------------| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
 | `affinity`                                            | node/pod affinities                                                                                                                                                                                                                                              | None                                                                                                 |
 | `alphaConfig.annotations`                             | Configmap annotations                                                                                                                                                                                                                                            | `{}`                                                                                                 |
 | `alphaConfig.configData`                              | Arbitrary configuration data to append                                                                                                                                                                                                                           | `{}`                                                                                                 |
@@ -174,11 +174,14 @@ The following table lists the configurable parameters of the oauth2-proxy chart
 | `checkDeprecation`                                    | Enable deprecation checks                                                                                                                                                                                                                                        | `true`                                                                                               |
 | `config.clientID`                                     | oauth client ID                                                                                                                                                                                                                                                  | `""`                                                                                                 |
 | `config.clientSecret`                                 | oauth client secret                                                                                                                                                                                                                                              | `""`                                                                                                 |
-| `config.configFile`                                   | custom [oauth2_proxy.cfg](https://github.com/oauth2-proxy/oauth2-proxy/blob/master/contrib/oauth2-proxy.cfg.example) contents for settings not overridable via environment nor command line                                                                      | `""`                                                                                                 |
+| `config.configFile`                                   | custom [oauth2_proxy.cfg](https://github.com/oauth2-proxy/oauth2-proxy/blob/master/contrib/oauth2-proxy.cfg.example) contents for settings not overridable via environment nor command line. Ignored when `alphaConfig.enabled=true` and `config.forceLegacyConfig=false` | `""`                                                                                                 |
 | `config.cookieName`                                   | The name of the cookie that oauth2-proxy will create.                                                                                                                                                                                                            | `""`                                                                                                 |
 | `config.cookieSecret`                                 | server specific cookie for the secret; create a new one with `openssl rand -base64 32 \| head -c 32 \| base64`                                                                                                                                                   | `""`                                                                                                 |
-| `config.existingConfig`                               | existing Kubernetes configmap to use for the configuration file. See [config template](https://github.com/oauth2-proxy/manifests/blob/master/helm/oauth2-proxy/templates/configmap.yaml) for the required values                                                 | `nil`                                                                                                |
+| `config.upstreams`                                    | Legacy upstreams used only when the chart generates `oauth2_proxy.cfg` and `alphaConfig` is disabled. Under `alphaConfig`, define upstreams in `alphaConfig.configData.upstreamConfig`                                                                          | `['file:///dev/null']`                                                                               |
+| `config.emailDomains`                                 | Email domains used when the chart generates `oauth2_proxy.cfg`. This remains the only generated legacy setting when `alphaConfig.enabled=true`                                                                                                                   | `['*']`                                                                                              |
+| `config.existingConfig`                               | existing Kubernetes configmap to use for the configuration file. Ignored when `alphaConfig.enabled=true` and `config.forceLegacyConfig=false`. See [config template](https://github.com/oauth2-proxy/manifests/blob/master/helm/oauth2-proxy/templates/configmap.yaml) for the required values | `nil`                                                                                                |
 | `config.existingSecret`                               | existing Kubernetes secret to use for OAuth2 credentials. See [oauth2-proxy.secrets helper](https://github.com/oauth2-proxy/manifests/blob/main/helm/oauth2-proxy/templates/_helpers.tpl#L157C13-L157C33) for the required values                                | `nil`                                                                                                |
+| `config.forceLegacyConfig`                            | When `alphaConfig.enabled=true`, keep using custom legacy `config.configFile` or `config.existingConfig` when `true`; when `false`, ignore both and generate only `email_domains` in `oauth2_proxy.cfg`                                                         | `true`                                                                                               |
 | `config.google.adminEmail`                            | user impersonated by the Google service account                                                                                                                                                                                                                  | `""`                                                                                                 |
 | `config.google.existingConfig`                        | existing Kubernetes configmap to use for the service account file. See [Google secret template](https://github.com/oauth2-proxy/manifests/blob/master/helm/oauth2-proxy/templates/google-secret.yaml) for the required values                                    | `nil`                                                                                                |
 | `config.google.groups`                                | restrict logins to members of these Google groups                                                                                                                                                                                                                | `[]`                                                                                                 |
@@ -372,7 +375,7 @@ gatewayApi:
     example.com/annotation: "value"
 ```
 
-If you don't specify custom rules, the chart will create a default rule that matches all paths with `PathPrefix: /` and routes to the oauth2-proxy service. 
+If you don't specify custom rules, the chart will create a default rule that matches all paths with `PathPrefix: /` and routes to the oauth2-proxy service.
 If you don't specify a sectionName, the rules will be applied to all listeners of the referenced Gateway.
 
 ## TLS Configuration
@@ -461,7 +464,11 @@ extraObjects:
 ```
 
 ## Multi whitelist-domain configuration
-You must use the config.configFile section for a multi-whitelist-domain configuration for one Oauth2-proxy instance.
+Use the structured `config.emailDomains` and `config.upstreams` values when they cover your case.
+
+Use `config.configFile` only when you need legacy `oauth2_proxy.cfg` settings that are not exposed as structured chart values, such as `whitelist_domains`.
+
+When `alphaConfig.enabled=true`, upstreams belong in `alphaConfig.configData.upstreamConfig`. If you also set `config.forceLegacyConfig=false`, the chart ignores both `config.configFile` and `config.existingConfig` and generates a minimal legacy config with only `email_domains`.
 
 It will be overwriting the `/etc/oauth2_proxy/oauth2_proxy.cfg` [configuration file](https://oauth2-proxy.github.io/oauth2-proxy/configuration/overview#config-file).
 In this example, Google provider is used, but you can find all other provider configurations here [oauth_provider](https://oauth2-proxy.github.io/oauth2-proxy/configuration/providers/).
@@ -482,5 +489,14 @@ config:
     provider = "google"
 ```
 
+## Alpha config migration
+When moving to `alphaConfig`, keep one main-config source in mind:
+
+1. The chart always mounts `/etc/oauth2_proxy/oauth2_proxy.cfg`.
+2. If `config.forceLegacyConfig=false`, the chart ignores both the `config.configFile` and `config.existingConfig` overrides and only generates a minimal necessary legacy config.
+3. If `config.existingConfig` is set and `config.forceLegacyConfig=true`, the external ConfigMap is mounted into the mounted file.
+4. If `config.configFile` is set and `config.forceLegacyConfig=true`, the chart renders that inline content into the mounted file.
+5. Put upstream definitions in `alphaConfig.configData.upstreamConfig`, not in the legacy `config.upstreams` or a legacy config file which will be ignored by the alpha mode.
+
 ## Route requests to sidecar container
 You can route requests to a sidecar container first by setting the `service.targetPort` variable. The possible values for the targetPort field of a Kubernetes Service can be either a port number or the name of a port defined in the pod. By default, the service's `targetPort` value equals to `httpSchema`'s.
diff --git a/helm/oauth2-proxy/ci/alphaconfig-1-legacy-true-values.yaml b/helm/oauth2-proxy/ci/alphaconfig-1-legacy-true-values.yaml
index fd40dfc6..469f9a5b 100644
--- a/helm/oauth2-proxy/ci/alphaconfig-1-legacy-true-values.yaml
+++ b/helm/oauth2-proxy/ci/alphaconfig-1-legacy-true-values.yaml
@@ -17,4 +17,4 @@ alphaConfig:
 
 # Implicit through default values, but explicitly set here for clarity in the test case
 config:
-  forceLegacyConfig: true
\ No newline at end of file
+  forceLegacyConfig: true
diff --git a/helm/oauth2-proxy/ci/alphaconfig-3-custom-configfile-legacy-true-values.yaml b/helm/oauth2-proxy/ci/alphaconfig-3-custom-configfile-legacy-true-values.yaml
index 8dd2786c..64dd5204 100644
--- a/helm/oauth2-proxy/ci/alphaconfig-3-custom-configfile-legacy-true-values.yaml
+++ b/helm/oauth2-proxy/ci/alphaconfig-3-custom-configfile-legacy-true-values.yaml
@@ -18,5 +18,5 @@ alphaConfig:
 config:
   configFile: |-
     email_domains = [ "example.com" ]
-    pass_access_token = true
+    encode_state = true
   forceLegacyConfig: true
diff --git a/helm/oauth2-proxy/ci/alphaconfig-5-existing-configmap-legacy-false-values.yaml b/helm/oauth2-proxy/ci/alphaconfig-5-existing-configmap-legacy-false-values.yaml
index e0e0e16c..370eb62e 100644
--- a/helm/oauth2-proxy/ci/alphaconfig-5-existing-configmap-legacy-false-values.yaml
+++ b/helm/oauth2-proxy/ci/alphaconfig-5-existing-configmap-legacy-false-values.yaml
@@ -27,4 +27,4 @@ extraObjects:
     data:
       oauth2_proxy.cfg: |
         email_domains = [ "ignored.example.com" ]
-        upstreams = [ "http://ignored-backend:8080" ]
\ No newline at end of file
+        upstreams = [ "http://ignored-backend:8080" ]
diff --git a/helm/oauth2-proxy/ci/alphaconfig-6-existing-configmap-legacy-true-values.yaml b/helm/oauth2-proxy/ci/alphaconfig-6-existing-configmap-legacy-true-values.yaml
index c1372470..d56e2d85 100644
--- a/helm/oauth2-proxy/ci/alphaconfig-6-existing-configmap-legacy-true-values.yaml
+++ b/helm/oauth2-proxy/ci/alphaconfig-6-existing-configmap-legacy-true-values.yaml
@@ -27,4 +27,4 @@ extraObjects:
     data:
       oauth2_proxy.cfg: |
         email_domains = [ "legacy.example.com" ]
-        pass_access_token = true
\ No newline at end of file
+        encode_state = true
diff --git a/helm/oauth2-proxy/ci/alphaconfig-custom-configfile-legacy-false-values.yaml b/helm/oauth2-proxy/ci/alphaconfig-custom-configfile-legacy-false-values.yaml
deleted file mode 100644
index bc84fb77..00000000
--- a/helm/oauth2-proxy/ci/alphaconfig-custom-configfile-legacy-false-values.yaml
+++ /dev/null
@@ -1,21 +0,0 @@
-# Test Case 6: alphaConfig enabled + custom configFile + forceLegacyConfig=false
-# Expected: ConfigMap with ONLY email_domains (ignores custom configFile)
-
-alphaConfig:
-  enabled: true
-  configData:
-    providers:
-      - id: google
-        provider: google
-        clientID: fake-client-id
-        clientSecret: fake-client-secret
-    upstreamConfig:
-      upstreams:
-        - id: alpha-service
-          path: /
-          uri: http://alpha-backend:8080
-
-config:
-  configFile: |-
-    email_domains = [ "example.com" ]
-  forceLegacyConfig: false
diff --git a/helm/oauth2-proxy/ci/alphaconfig-custom-configfile-legacy-true-values.yaml b/helm/oauth2-proxy/ci/alphaconfig-custom-configfile-legacy-true-values.yaml
deleted file mode 100644
index f86b22ff..00000000
--- a/helm/oauth2-proxy/ci/alphaconfig-custom-configfile-legacy-true-values.yaml
+++ /dev/null
@@ -1,21 +0,0 @@
-# Test Case 5: alphaConfig enabled + custom configFile + forceLegacyConfig=true
-# Expected: ConfigMap with custom configFile content (backward compatible)
-
-alphaConfig:
-  enabled: true
-  configData:
-    providers:
-      - id: google
-        provider: google
-        clientID: fake-client-id
-        clientSecret: fake-client-secret
-    upstreamConfig:
-      upstreams:
-        - id: alpha-service
-          path: /
-          uri: http://alpha-backend:8080
-
-config:
-  configFile: |-
-    email_domains = [ "example.com" ]
-  forceLegacyConfig: true
diff --git a/helm/oauth2-proxy/ci/alphaconfig-legacy-false-values.yaml b/helm/oauth2-proxy/ci/alphaconfig-legacy-false-values.yaml
deleted file mode 100644
index 99db3dfd..00000000
--- a/helm/oauth2-proxy/ci/alphaconfig-legacy-false-values.yaml
+++ /dev/null
@@ -1,19 +0,0 @@
-# Test Case 4: alphaConfig enabled with forceLegacyConfig=false
-# Expected: ConfigMap with ONLY email_domains (no upstreams) - FIX for issue #226
-
-alphaConfig:
-  enabled: true
-  configData:
-    providers:
-      - id: google
-        provider: google
-        clientID: fake-client-id
-        clientSecret: fake-client-secret
-    upstreamConfig:
-      upstreams:
-        - id: alpha-service
-          path: /
-          uri: http://alpha-backend:8080
-
-config:
-  forceLegacyConfig: false
diff --git a/helm/oauth2-proxy/ci/alphaconfig-legacy-true-values.yaml b/helm/oauth2-proxy/ci/alphaconfig-legacy-true-values.yaml
deleted file mode 100644
index b3cf6537..00000000
--- a/helm/oauth2-proxy/ci/alphaconfig-legacy-true-values.yaml
+++ /dev/null
@@ -1,19 +0,0 @@
-# Test Case 3: alphaConfig enabled with forceLegacyConfig=true (default)
-# Expected: legacy ConfigMap containing only email_domains (upstreams omitted)
-
-alphaConfig:
-  enabled: true
-  configData:
-    providers:
-      - id: google
-        provider: google
-        clientID: fake-client-id
-        clientSecret: fake-client-secret
-    upstreamConfig:
-      upstreams:
-        - id: alpha-service
-          path: /
-          uri: http://alpha-backend:8080
-
-config:
-  forceLegacyConfig: true
diff --git a/helm/oauth2-proxy/ci/custom-configfile-values.yaml b/helm/oauth2-proxy/ci/custom-configfile-values.yaml
deleted file mode 100644
index 2db37929..00000000
--- a/helm/oauth2-proxy/ci/custom-configfile-values.yaml
+++ /dev/null
@@ -1,9 +0,0 @@
-# Test Case 2: Custom configFile (alphaConfig disabled)
-# Expected: ConfigMap with custom configFile content
-
-config:
-  configFile: |-
-    email_domains = [ "example.com" ]
-    upstreams = [ "http://backend:8080" ]
-    pass_basic_auth = false
-    pass_access_token = true
diff --git a/helm/oauth2-proxy/templates/_helpers.tpl b/helm/oauth2-proxy/templates/_helpers.tpl
index 94b6f557..204bd7eb 100644
--- a/helm/oauth2-proxy/templates/_helpers.tpl
+++ b/helm/oauth2-proxy/templates/_helpers.tpl
@@ -163,6 +163,44 @@ metricsServer:
 {{- end }}
 {{- end -}}
 
+{{/*
+If `config.forceLegacyConfig=false`, the chart ignores both the `config.configFile` and `config.existingConfig` overrides and only generates a minimal necessary legacy config.
+If `config.existingConfig` is set and `config.forceLegacyConfig=true`, the external ConfigMap is mounted into the mounted file.
+If `config.configFile` is set and `config.forceLegacyConfig=true`, the chart renders that inline content into the mounted file.
+*/}}
+{{- define "oauth2-proxy.legacy-config.mode" -}}
+{{- if and .Values.alphaConfig.enabled (not .Values.config.forceLegacyConfig) -}}
+generated-alpha-compatible
+{{- else if .Values.config.existingConfig -}}
+existing-configmap
+{{- else if .Values.config.configFile -}}
+inline-custom
+{{- else if .Values.alphaConfig.enabled -}}
+generated-alpha-compatible
+{{- else -}}
+generated-legacy
+{{- end -}}
+{{- end -}}
+
+{{- define "oauth2-proxy.legacy-config.name" -}}
+{{- if eq (include "oauth2-proxy.legacy-config.mode" .) "existing-configmap" -}}
+{{- .Values.config.existingConfig -}}
+{{- else -}}
+{{- template "oauth2-proxy.fullname" . -}}
+{{- end -}}
+{{- end -}}
+
+{{- define "oauth2-proxy.legacy-config.content" -}}
+{{- if eq (include "oauth2-proxy.legacy-config.mode" .) "inline-custom" -}}
+{{- tpl .Values.config.configFile $ -}}
+{{- else if eq (include "oauth2-proxy.legacy-config.mode" .) "generated-alpha-compatible" -}}
+email_domains = {{ .Values.config.emailDomains | toJson }}
+{{- else -}}
+email_domains = {{ .Values.config.emailDomains | toJson }}
+upstreams = {{ .Values.config.upstreams | toJson }}
+{{- end -}}
+{{- end -}}
+
 {{- define "oauth2-proxy.secrets" -}}
 {{- if has "cookie-secret" .Values.config.requiredSecretKeys }}
 cookie-secret: {{ tpl .Values.config.cookieSecret $ | b64enc | quote }}
diff --git a/helm/oauth2-proxy/templates/configmap.yaml b/helm/oauth2-proxy/templates/configmap.yaml
index 96e4c93d..30e25c55 100644
--- a/helm/oauth2-proxy/templates/configmap.yaml
+++ b/helm/oauth2-proxy/templates/configmap.yaml
@@ -1,4 +1,4 @@
-{{- if not .Values.config.existingConfig }}
+{{- if ne (include "oauth2-proxy.legacy-config.mode" .) "existing-configmap" }}
 apiVersion: v1
 kind: ConfigMap
 metadata:
@@ -12,11 +12,6 @@ metadata:
   name: {{ template "oauth2-proxy.fullname" . }}
   namespace: {{ template "oauth2-proxy.namespace" $ }}
 data:
-  {{- if and .Values.config.configFile (or (not .Values.alphaConfig.enabled) .Values.config.forceLegacyConfig) }}
-  oauth2_proxy.cfg: {{ tpl .Values.config.configFile $ | quote }}
-  {{- else if .Values.alphaConfig.enabled }}
-  oauth2_proxy.cfg: {{ printf "email_domains = %s" (.Values.config.emailDomains | toJson) | quote }}
-  {{- else }}
-  oauth2_proxy.cfg: {{ printf "email_domains = %s\nupstreams = %s" (.Values.config.emailDomains | toJson) (.Values.config.upstreams | toJson) | quote }}
-  {{- end }}
+  oauth2_proxy.cfg: |
+{{ include "oauth2-proxy.legacy-config.content" . | nindent 4 }}
 {{- end }}
diff --git a/helm/oauth2-proxy/templates/deployment.yaml b/helm/oauth2-proxy/templates/deployment.yaml
index a9341dad..be694675 100644
--- a/helm/oauth2-proxy/templates/deployment.yaml
+++ b/helm/oauth2-proxy/templates/deployment.yaml
@@ -27,8 +27,8 @@ spec:
   template:
     metadata:
       annotations:
-        {{- if not .Values.config.existingConfig }}
-        checksum/config: {{ include (print $.Template.BasePath "/configmap.yaml") . | sha256sum }}
+        {{- if ne (include "oauth2-proxy.legacy-config.mode" .) "existing-configmap" }}
+        checksum/config: {{ include "oauth2-proxy.legacy-config.content" . | sha256sum }}
         {{- end }}
         {{- if .Values.alphaConfig.enabled }}
         checksum/alpha-config: {{ include "oauth2-proxy.alpha-config" . | sha256sum }}
@@ -370,7 +370,7 @@ spec:
 {{- end }}
       - configMap:
           defaultMode: 420
-          name: {{ if .Values.config.existingConfig }}{{ .Values.config.existingConfig }}{{ else }}{{ template "oauth2-proxy.fullname" . }}{{ end }}
+          name: {{ include "oauth2-proxy.legacy-config.name" . | trim }}
         name: configmain
 {{- if .Values.alphaConfig.enabled }}
 {{- if .Values.alphaConfig.existingConfig }}
diff --git a/helm/oauth2-proxy/values.yaml b/helm/oauth2-proxy/values.yaml
index 4590da3b..dd2f6592 100644
--- a/helm/oauth2-proxy/values.yaml
+++ b/helm/oauth2-proxy/values.yaml
@@ -56,40 +56,41 @@ config:
     #  - group1@example.com
     #  - group2@example.com
   #
-  # Configuration file generation / precedence
-  # 1. If config.existingConfig is set, that external ConfigMap is used
-  #    and no chart-managed ConfigMap is generated. configFile,
-  #    emailDomains and upstreams are all ignored.
-  # 2. If configFile is set, it takes precedence over the structured
-  #    config below (except when alphaConfig.enabled=true and
-  #    forceLegacyConfig=false, in which case configFile is ignored).
+  # Configuration file generation precedence
+  # 1. If configFile is set, it takes precedence over the structured
+  #    config below.
+  # 2. When alphaConfig.enabled=true and forceLegacyConfig=false,
+  #    both configFile and existingConfig are ignored and the chart
+  #    generates a minimal legacy config from emailDomains only.
   # 3. If configFile is empty/not set, the config is auto-generated
-  #    from emailDomains and upstreams.
+  #    from emailDomains and, when alphaConfig is disabled, upstreams.
   configFile: ""
-  # Email domains allowed to authenticate (used when configFile is
-  # empty)
+  # Email domains allowed to authenticate when the chart generates
+  # the main oauth2_proxy.cfg.
+  # This is always included in generated config, including the
+  # minimal alphaConfig-compatible legacy config.
   emailDomains: ["*"]
-  # Legacy upstream configuration (used when configFile is empty
-  # and alphaConfig is disabled)
+  # Legacy upstream configuration used only when the chart generates
+  # oauth2_proxy.cfg and alphaConfig is disabled.
   # When alphaConfig.enabled is true, define upstreams in
-  # alphaConfig.configData.upstreamConfig instead
+  # alphaConfig.configData.upstreamConfig instead.
   upstreams: ["file:///dev/null"]
   # Behavior when using alphaConfig together with a custom config file
   #
   # This flag only has an effect when:
   #   - alphaConfig.enabled is true, AND
-  #   - you provide a custom config.configFile.
+  #   - you provide a custom config.configFile or config.existingConfig.
   #
   # Auto-generated config when alphaConfig.enabled=true is always a
   # minimal legacy config (no upstreams), regardless of this flag.
   #
-  # When true (default): Honor a custom configFile
+  # When true (default): Honor a custom configFile/existingConfig
   # even when alphaConfig.enabled=true. If your custom config still
   # contains deprecated options (for example 'upstreams'),
   # oauth2-proxy may fail with:
   #   "failed to load core options: '' has invalid keys: upstreams"
   #
-  # When false: Ignore any custom configFile when
+  # When false: Ignore any custom configFile/existingConfig when
   # alphaConfig.enabled=true and instead generate the minimal
   # legacy config. This preserves compatibility and avoids
   # invalid legacy options such as 'upstreams'.
@@ -102,7 +103,8 @@ config:
   #      is alpha-compatible (remove 'upstreams' and any other
   #      keys no longer supported).
   # 2) Set forceLegacyConfig: false:
-  #    - The chart will ignore config.configFile for alphaConfig.
+  #    - The chart will ignore config.configFile and
+  #      config.existingConfig for alphaConfig.
   #    - Define upstreams in alphaConfig.configData.upstreamConfig
   #      instead (see examples below).
   #    - Move any other relevant settings into alphaConfig and/or
@@ -110,15 +112,18 @@ config:
   forceLegacyConfig: true
   #
   # Custom configuration file: oauth2_proxy.cfg (overrides
-  # emailDomains and upstreams)
+  # emailDomains and upstreams when it is honored)
   # Example:
   # configFile: |-
   #   email_domains = [ "*" ]
   #   pass_basic_auth = false
   #   pass_access_token = true
   # Use an existing config map (see configmap.yaml for required fields)
+  # This is ignored when alphaConfig.enabled=true and
+  # forceLegacyConfig=false.
   # Example:
   # existingConfig: config
+  existingConfig: ~
 
 alphaConfig:
   enabled: false

From f0479cbc9afe455288bdd10f69bc5a86980797cc Mon Sep 17 00:00:00 2001
From: Jan Larwig <jan@larwig.com>
Date: Mon, 23 Mar 2026 16:35:28 +0100
Subject: [PATCH 4/5] doc: reword how to use the alpha config

Signed-off-by: Jan Larwig <jan@larwig.com>
---
 helm/oauth2-proxy/README.md | 20 ++++++++++++++------
 1 file changed, 14 insertions(+), 6 deletions(-)

diff --git a/helm/oauth2-proxy/README.md b/helm/oauth2-proxy/README.md
index b7cd10b1..4bf24b49 100644
--- a/helm/oauth2-proxy/README.md
+++ b/helm/oauth2-proxy/README.md
@@ -490,13 +490,21 @@ config:
 ```
 
 ## Alpha config migration
-When moving to `alphaConfig`, keep one main-config source in mind:
+When moving to `alphaConfig`, keep one main config source in mind. The Alpha Config will take precedence and all options
+that are already supported by the Alpha Config will need to be removed from the legacy toml config. Have a look at the 
+[Alpha Config documentation](https://oauth2-proxy.github.io/oauth2-proxy/configuration/alpha-config/).
 
-1. The chart always mounts `/etc/oauth2_proxy/oauth2_proxy.cfg`.
-2. If `config.forceLegacyConfig=false`, the chart ignores both the `config.configFile` and `config.existingConfig` overrides and only generates a minimal necessary legacy config.
-3. If `config.existingConfig` is set and `config.forceLegacyConfig=true`, the external ConfigMap is mounted into the mounted file.
-4. If `config.configFile` is set and `config.forceLegacyConfig=true`, the chart renders that inline content into the mounted file.
-5. Put upstream definitions in `alphaConfig.configData.upstreamConfig`, not in the legacy `config.upstreams` or a legacy config file which will be ignored by the alpha mode.
+Keep the following in mind:
+
+- The chart always mounts `/etc/oauth2_proxy/oauth2_proxy.cfg`. (Legacy toml config)
+- Per default `config.forceLegacyConfig` is `true`
+
+The evaluation happens in the following order:
+
+1. If `config.forceLegacyConfig=false`, the chart ignores both the `config.configFile` and `config.existingConfig` overrides and only generates a minimal necessary legacy config.
+2. If `config.existingConfig` is set and `config.forceLegacyConfig=true`, the external ConfigMap is used as the mounted file.
+3. If `config.configFile` is set and `config.forceLegacyConfig=true`, the chart renders that inline content into the mounted file.
+4. Reminder: Put your upstream definitions inot `alphaConfig.configData.upstreamConfig`, not in the legacy `config.upstreams` or a legacy config file which will cause an error with the alpha config.
 
 ## Route requests to sidecar container
 You can route requests to a sidecar container first by setting the `service.targetPort` variable. The possible values for the targetPort field of a Kubernetes Service can be either a port number or the name of a port defined in the pod. By default, the service's `targetPort` value equals to `httpSchema`'s.

From 8bb02dad56a66fb2d0291910cce6943499a5a2a3 Mon Sep 17 00:00:00 2001
From: Pierluigi Lenoci <pierluigi.lenoci@gmail.com>
Date: Mon, 23 Mar 2026 17:46:41 +0100
Subject: [PATCH 5/5] =?UTF-8?q?fix:=20typo=20in=20README.md=20"inot"=20?=
 =?UTF-8?q?=E2=86=92=20"into"?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Pierluigi Lenoci <pierluigi.lenoci@gmail.com>
---
 helm/oauth2-proxy/README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/helm/oauth2-proxy/README.md b/helm/oauth2-proxy/README.md
index 4bf24b49..d63d53df 100644
--- a/helm/oauth2-proxy/README.md
+++ b/helm/oauth2-proxy/README.md
@@ -504,7 +504,7 @@ The evaluation happens in the following order:
 1. If `config.forceLegacyConfig=false`, the chart ignores both the `config.configFile` and `config.existingConfig` overrides and only generates a minimal necessary legacy config.
 2. If `config.existingConfig` is set and `config.forceLegacyConfig=true`, the external ConfigMap is used as the mounted file.
 3. If `config.configFile` is set and `config.forceLegacyConfig=true`, the chart renders that inline content into the mounted file.
-4. Reminder: Put your upstream definitions inot `alphaConfig.configData.upstreamConfig`, not in the legacy `config.upstreams` or a legacy config file which will cause an error with the alpha config.
+4. Reminder: Put your upstream definitions into `alphaConfig.configData.upstreamConfig`, not in the legacy `config.upstreams` or a legacy config file which will cause an error with the alpha config.
 
 ## Route requests to sidecar container
 You can route requests to a sidecar container first by setting the `service.targetPort` variable. The possible values for the targetPort field of a Kubernetes Service can be either a port number or the name of a port defined in the pod. By default, the service's `targetPort` value equals to `httpSchema`'s.