feat: add forceLegacyConfig flag for alphaConfig compatibility (#385)

pierluigilenoci · tuunit · web-flow · commit 727b5ecb2aa1 · 2026-03-26T19:08:11.000+01:00
* 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 &lt;pierluigi.lenoci@gmail.com&gt;

* test(ci): update test case files for config testing

Signed-off-by: Jan Larwig &lt;jan@larwig.com&gt;

* 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 &lt;jan@larwig.com&gt;

* doc: reword how to use the alpha config

Signed-off-by: Jan Larwig &lt;jan@larwig.com&gt;

* fix: typo in README.md "inot" → "into"

Signed-off-by: Pierluigi Lenoci &lt;pierluigi.lenoci@gmail.com&gt;

---------

Signed-off-by: Pierluigi Lenoci &lt;pierluigi.lenoci@gmail.com&gt;
Signed-off-by: Jan Larwig &lt;jan@larwig.com&gt;
Co-authored-by: Jan Larwig &lt;jan@larwig.com&gt;
diff --git a/helm/oauth2-proxy/Chart.yaml b/helm/oauth2-proxy/Chart.yaml
@@ -1,5 +1,5 @@
 name: oauth2-proxy
-version: 10.3.0
+version: 10.4.0
 apiVersion: v2
 appVersion: 7.15.0
 home: https://oauth2-proxy.github.io/oauth2-proxy/
@@ -30,8 +30,23 @@ 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: Add tpl support for config.cookieName, config.existingSecret, customLabels, image.registry, imagePullSecrets, and networkPolicy.ingress/egress
+      description: Added comprehensive alphaConfig examples with upstreamConfig configuration
       links:
-        - name: GitHub PR
-          url: https://github.com/oauth2-proxy/manifests/pull/398
+        - name: GitHub Issue
+          url: https://github.com/oauth2-proxy/manifests/issues/311
diff --git 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                                                                                                                                                                                                                | `[]`                                                                                                 |
@@ -373,7 +376,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
@@ -462,7 +465,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/).
@@ -483,5 +490,22 @@ config:
     provider = "google"
 ```
 
+## Alpha config migration
+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/).
+
+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 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.
diff --git a/helm/oauth2-proxy/ci/alphaconfig-1-legacy-true-values.yaml 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
diff --git a/helm/oauth2-proxy/ci/alphaconfig-2-legacy-false-values.yaml 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
@@ -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" ]
+    encode_state = 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
@@ -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
@@ -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" ]
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
@@ -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" ]
+        encode_state = true
diff --git a/helm/oauth2-proxy/ci/existing-configmap-values.yaml b/helm/oauth2-proxy/ci/existing-configmap-values.yaml
@@ -0,0 +1,13 @@
+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/_helpers.tpl b/helm/oauth2-proxy/templates/_helpers.tpl
diff --git a/helm/oauth2-proxy/templates/configmap.yaml b/helm/oauth2-proxy/templates/configmap.yaml
diff --git a/helm/oauth2-proxy/templates/deployment.yaml b/helm/oauth2-proxy/templates/deployment.yaml
diff --git a/helm/oauth2-proxy/values.yaml b/helm/oauth2-proxy/values.yaml
