feat: Add forceLegacyConfig flag for alphaConfig compatibility

[pierluigilenoci]

Summary

This PR fixes critical bugs in alphaConfig integration and introduces the forceLegacyConfig flag to provide backward compatibility for users with custom configuration files.

Problem Statement

Issue #226: alphaConfig fails with "invalid keys: upstreams"

When alphaConfig.enabled = true, oauth2-proxy loads BOTH configuration files:

• The legacy config file (oauth2_proxy.cfg) via --config flag
• The alpha config file (oauth2_proxy.yml) via --alpha-config flag

However, alphaConfig removed support for the upstreams option. If the legacy config contains upstreams, oauth2-proxy fails with:

failed to load core options: failed to load config: error unmarshalling config: '' has invalid keys: upstreams

Critical Bug: Missing email_domains validation

When alphaConfig.enabled=true with default values, the deployment was not mounting the ConfigMap or adding the --config flag, causing oauth2-proxy to fail with:

missing setting for email validation

Issue #302: Difficulty using external secrets with alphaConfig

Users wanting to load secrets from external sources (e.g., Azure Key Vault CSI Driver) lacked clear documentation on how to inject secrets via environment variables.

Issue #311: Missing alphaConfig documentation

Users needed examples showing how to configure upstreamConfig in alphaConfig mode, particularly for multi-upstream scenarios with path-based routing.

Solution

1. Fixed Critical Bug: Always mount ConfigMap

Commit: 7e6bd35

Fixed deployment template to ALWAYS mount the ConfigMap and add --config flag, regardless of alphaConfig settings. This ensures email_domains is always provided to oauth2-proxy.

2. Fixed alphaConfig Incompatibility

Commit: 9f00757

Changed the auto-generated legacy config logic:

• When alphaConfig DISABLED → Full legacy config with email_domains + upstreams
• When alphaConfig ENABLED → Minimal legacy config with email_domains ONLY (no upstreams)

This is because when alphaConfig is enabled, oauth2-proxy loads BOTH config files, and the legacy config CANNOT contain options removed by alphaConfig.

3. Introduced forceLegacyConfig Flag

Commit: 4a7c93a

Added config.forceLegacyConfig (default: true) to control whether custom configFile should be used when alphaConfig is enabled:

• forceLegacyConfig = true (default): Use custom configFile as-is (backward compatible)
• forceLegacyConfig = false: Ignore custom configFile and auto-generate minimal config

IMPORTANT: This flag ONLY affects custom configFile behavior. It does NOT control whether upstreams are included in auto-generated configs.

4. Structured Configuration

Changed from hardcoded config.configFile to structured fields:

• config.emailDomains: Email domains allowed to authenticate (default: [ "*" ])
• config.upstreams: Legacy upstream configuration (default: [ "file:///dev/null" ])
• config.configFile: Custom config template (empty by default)

5. Configuration Generation Logic

The configmap.yaml template now implements this logic:

alphaConfig	forceLegacyConfig	configFile	Generated Config
disabled	any	empty	email_domains + upstreams
disabled	any	custom	Uses custom configFile as-is
enabled	any	empty	email_domains ONLY (no upstreams)
enabled	true	custom	Uses custom configFile as-is
enabled	false	custom	email_domains ONLY (ignores custom)

Key Points:

• When alphaConfig is enabled, auto-generated config NEVER includes upstreams (regardless of forceLegacyConfig)
• forceLegacyConfig only controls whether to use or ignore custom configFile when alphaConfig is enabled
• ConfigMap is ALWAYS mounted and --config flag is ALWAYS added

6. Comprehensive Documentation

Added examples for:

• alphaConfig upstreams: Multi-upstream configuration with path-based routing, rewriteTarget, injectResponseHeaders
• External secrets: Using extraEnv to load secrets from Azure Key Vault CSI Driver
• forceLegacyConfig usage: Clear instructions on when and how to use the flag

Migration Guide

For most users (NOT experiencing issue #226)

No action required. The chart now works correctly with alphaConfig enabled using default values.

For users experiencing "invalid keys: upstreams" error

If you're getting this error with alphaConfig enabled, you have two options:

Option A: Use alphaConfig upstreams (RECOMMENDED)

config:
  emailDomains: [ "*" ]
  # Remove upstreams from config - let chart auto-generate minimal legacy config

alphaConfig:
  enabled: true
  configData:
    upstreamConfig:
      upstreams:
        - id: backend
          path: /
          uri: http://backend:8080

Option B: Use custom configFile with forceLegacyConfig
If you have a custom config.configFile that includes upstreams:

config:
  forceLegacyConfig: false  # Ignore custom configFile
  emailDomains: [ "*" ]

alphaConfig:
  enabled: true
  configData:
    upstreamConfig:
      upstreams:
        - id: backend
          path: /
          uri: http://backend:8080

For users with custom configFile (backward compatibility)

If you have a custom config.configFile that does NOT contain removed alphaConfig options:

config:
  forceLegacyConfig: true  # Use custom configFile (default)
  configFile: |
    email_domains = [ "*" ]
    # Your other legacy config options

alphaConfig:
  enabled: true
  configData:
    upstreamConfig:
      upstreams:
        - id: backend
          path: /
          uri: http://backend:8080

Testing

Commit: 88ae305

Created comprehensive CI test suite covering all configuration scenarios:

• ✅ Custom configFile (alphaConfig disabled)
• ✅ alphaConfig with forceLegacyConfig=true (backward compatible)
• ✅ alphaConfig with forceLegacyConfig=false (fix for failed to load alpha options: unable to load config file: read /etc/oauth2_proxy/oauth2_proxy.yml: is a directory #226)
• ✅ alphaConfig + custom configFile + forceLegacyConfig=true
• ✅ alphaConfig + custom configFile + forceLegacyConfig=false
• ✅ Existing external ConfigMap via extraObjects

All test cases pass successfully.

Breaking Changes

None. This is a non-breaking change.

• ConfigMap is now always mounted (fixes bug, doesn't break existing deployments)
• Default behavior with alphaConfig now works correctly
• forceLegacyConfig defaults to true for backward compatibility with custom configFiles

Checklist

• Chart version bumped to 10.1.0 (minor version for new feature)
• Changelog updated in Chart.yaml
• Comprehensive test suite created with 6 CI test scenarios
• Documentation added with examples
• DCO sign-off included in all commits
• Zero breaking changes confirmed via testing

Related Issues

• Fixes failed to load alpha options: unable to load config file: read /etc/oauth2_proxy/oauth2_proxy.yml: is a directory #226
• Closes Architectural problems with the alpha secret #302
• Closes Does alphaConfig upstreams is fully supported in production config in app version 7.9.0 helm version 7.12.14 #311

[tuunit]

Isn't this a breaking change?

[pierluigilenoci]

No, it is not a breaking change. Here's why:

The Scenario Didn't Work Before

When alphaConfig.enabled=true without a custom configFile, the old chart:

• Did not generate a ConfigMap (required configFile to exist)
• Did not mount the config or add --config flag
• Failed with error: missing setting for email validation

This scenario was broken before this PR.

This PR Fixes That Bug

Now with this PR, the same scenario:

• Automatically generates a minimal ConfigMap with email_domains
• Always mounts it and adds --config flag
• Works correctly - fixes issue failed to load alpha options: unable to load config file: read /etc/oauth2_proxy/oauth2_proxy.yml: is a directory #226

What forceLegacyConfig: true Does

The default forceLegacyConfig: true preserves behavior for users who DO have a custom configFile:

Before PR (with custom configFile):

config:
  configFile: |
    email_domains = ["*"]
    upstreams = ["http://backend"]
alphaConfig:
  enabled: true

→ Uses the custom configFile

After PR (with custom configFile + default):

config:
  forceLegacyConfig: true  # DEFAULT
  configFile: |
    email_domains = ["*"]
    upstreams = ["http://backend"]
alphaConfig:
  enabled: true

→ Still uses the custom configFile (identical behavior)

Not Breaking Because

1. The scenario without custom configFile didn't work before → now it works (bug fix)
2. The scenario with custom configFile works the same with the default (backward compatible)
3. All CI tests pass, confirming no regressions

The tests validate both scenarios work correctly.