feat: introduce GatewayConfig CRD for gateway-scoped configuration #1623

sqaisar · 2025-12-05T19:25:50Z

Description

Introduce GatewayConfig CRD for gateway-scoped configuration of the external processor. Adds controller lifecycle handling (including finalizer management), deprecates AIGatewayRoute-level resource configuration in favor of GatewayConfig, and updates docs with migration guidance and new options.

Example

apiVersion: aigateway.envoyproxy.io/v1alpha1
kind: GatewayConfig
metadata:
  name: my-gateway-config
  namespace: default
spec:
  extProc:
   kubernetes:
      env:
        - name: OTEL_EXPORTER_OTLP_ENDPOINT
          value: "http://otel-collector:4317"
      resources:
        requests:
          cpu: "100m"
          memory: "128Mi"
        limits:
          cpu: "500m"
          memory: "512Mi"
---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: my-gateway
  namespace: default
  annotations:
    aigateway.envoyproxy.io/gateway-config: my-gateway-config
spec:
  gatewayClassName: envoy-gateway
  listeners:
    - name: http
      protocol: HTTP
      port: 8080

Related Issues/PRs (if applicable)

Fixes [1]

Special notes for reviewers (if applicable)

Docs, controller, and CRD changes included; route-level resources are deprecated—see migration guidance in docs.

1: #1552

mathetake

Thank you for taking a shot at this!

internal/controller/gateway_config.go

site/docs/capabilities/gateway-config.md

internal/controller/gateway_mutator.go

internal/controller/ai_gateway_route.go

api/v1alpha1/gateway_config.go

nacx

Just reviewed the API for now and left one comment.

Apart from that, this GatewayConfig object is only relevant for Kubernets, but not in standalone modes (at least for now). Would it make sense to convey that in the API? For example, the Envoy Gateaay infrastructure resources have the "provider" concept and settings are under a kubernetes config know.

Something like:

apiVersion: aigateway.envoyproxy.io/v1alpha1
kind: GatewayConfig
metadata:
  name: comprehensive-config
  namespace: default
spec:
  kubernetes:  
    extProc:
      env:
        (...)

or

apiVersion: aigateway.envoyproxy.io/v1alpha1
kind: GatewayConfig
metadata:
  name: comprehensive-config
  namespace: default
spec:
  extProc:  
    kubernetes:
      env:
        (...)

WDYT?

api/v1alpha1/gateway_config.go

This commit adds the GatewayConfig custom resource definition (CRD) to manage configuration for the AI Gateway external processor. It allows users to define environment variables and resource requirements at the gateway level, enhancing flexibility and reusability across multiple gateways. The AIGatewayRoute's resource configuration is now deprecated in favor of this new approach. Additionally, the GatewayConfig controller is implemented to handle the lifecycle of GatewayConfig resources, including finalizer management to prevent accidental deletions while still referenced by Gateways. Documentation updates are included to reflect the new configuration options and migration guidance from the deprecated route-level settings. Signed-off-by: Shabab Qaisar <[email protected]> Signed-off-by: Shabab Qaisar <[email protected]>

This commit refactors the GatewayConfig controller to eliminate finalizer management, simplifying the lifecycle handling of GatewayConfig resources. The controller now focuses on notifying referencing Gateways of changes without blocking deletion based on references. Additionally, the documentation has been updated to reflect these changes, including the removal of finalizer behavior descriptions from the API and capability documentation. Signed-off-by: Shabab Qaisar <[email protected]> Signed-off-by: Shabab Qaisar <[email protected]>

sqaisar · 2025-12-06T14:12:25Z

Thank you for taking a shot at this!

Thankyou for quickly reviewing the changes. I've resolved all of them. Please take a look.

…pec from the Envoy Gateway API Signed-off-by: Shabab Qaisar <[email protected]>

mathetake

looking good so far!

api/v1alpha1/gateway_config.go

…rSpec for defining the external processor's configuration. Signed-off-by: Shabab Qaisar <[email protected]>

Signed-off-by: Shabab Qaisar <[email protected]>

sqaisar · 2025-12-09T02:28:53Z

@mathetake I've updated the type to GatewayConfig.extProc.kubernetes
for now all changes looks concluded. Please review.

api/v1alpha1/gateway_config.go

internal/controller/controller.go

internal/controller/gateway_mutator.go

mathetake

Looks good to me modulo a few comments. Thank you so much for working on this! I will defer to @nacx for the rest as i will not be available to review at least for the next 48 hours

… GatewayConfig resources over route-scoped values. Signed-off-by: Shabab Qaisar <[email protected]>

…urations and list errors Signed-off-by: Shabab Qaisar <[email protected]>

sqaisar · 2025-12-09T13:17:49Z

Added more tests to make up for coverage.

codecov-commenter · 2025-12-09T14:13:56Z

Codecov Report

❌ Patch coverage is 58.36910% with 97 lines in your changes missing coverage. Please review.
✅ Project coverage is 82.98%. Comparing base (2c3b46f) to head (4901e49).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
...ers/externalversions/api/v1alpha1/gatewayconfig.go	0.00%	27 Missing ⚠️
internal/controller/gateway_mutator.go	74.00%	18 Missing and 8 partials ⚠️
...oned/typed/api/v1alpha1/fake/fake_gatewayconfig.go	0.00%	16 Missing ⚠️
...tset/versioned/typed/api/v1alpha1/gatewayconfig.go	0.00%	9 Missing ⚠️
internal/controller/gateway_config.go	89.39%	5 Missing and 2 partials ⚠️
...lpha1/client/listers/api/v1alpha1/gatewayconfig.go	0.00%	4 Missing ⚠️
...ientset/versioned/typed/api/v1alpha1/api_client.go	0.00%	2 Missing ⚠️
...rsioned/typed/api/v1alpha1/fake/fake_api_client.go	0.00%	2 Missing ⚠️
...formers/externalversions/api/v1alpha1/interface.go	0.00%	2 Missing ⚠️
...lpha1/client/informers/externalversions/generic.go	0.00%	2 Missing ⚠️

❌ Your patch status has failed because the patch coverage (58.36%) is below the target coverage (80.00%). You can increase the patch coverage or adjust the target coverage.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1623      +/-   ##
==========================================
- Coverage   83.46%   82.98%   -0.48%     
==========================================
  Files         138      143       +5     
  Lines       12540    12758     +218     
==========================================
+ Hits        10466    10587     +121     
- Misses       1440     1527      +87     
- Partials      634      644      +10

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

mathetake

LGTM! I will wait for other maintainers to take a look until tomorrow otherwise good to go!

cc @envoyproxy/ai-gateway-maintainers

internal/controller/gateway_mutator.go

Co-authored-by: Takeshi Yoneda <[email protected]> Signed-off-by: Shabab Qaisar <[email protected]>

sqaisar · 2025-12-16T09:33:47Z

LGTM! I will wait for other maintainers to take a look until tomorrow otherwise good to go!

cc @envoyproxy/ai-gateway-maintainers

Thankyou.

Xunzhuo · 2025-12-16T11:07:59Z

why not just use EnvoyProxy CR?

nacx · 2025-12-16T17:55:53Z

why not just use EnvoyProxy CR

Mostly because the configuration of the extproc container is generated on the fly by EAIGW, and its config can't be preconfigured in the EP resource.

nacx

Thanks @sqaisar! This looks great.
I've left a few comments mostly related to testing and I think this will be good to go once done!

internal/controller/gateway_config.go

internal/controller/gateway_config_test.go

internal/controller/gateway_mutator_test.go

examples/gateway-config/comprehensive.yaml

… facilitate e2e testing Signed-off-by: Shabab Qaisar <[email protected]>

sqaisar · 2025-12-17T07:49:52Z

Thanks @sqaisar! This looks great. I've left a few comments mostly related to testing and I think this will be good to go once done!

I've resolved them. Looks better i think.

Signed-off-by: Shabab Qaisar <[email protected]>

nacx · 2025-12-17T10:47:35Z

internal/controller/gateway_config_test.go

+	eventCh := internaltesting.NewControllerEventChan[*gwapiv1.Gateway]()
+	c := NewGatewayConfigController(fakeClient, ctrl.Log, eventCh.Ch)
+
+	// Create a Gateway that references a GatewayConfig that doesn't exist yet.


This is not what I meant. The thing we're missing in the tests is the behaviour when the referenced config does not exist (and will never exist). For example, users make a typo in the annotation value. What is the expected behaviour then? This is what I think this test needs to validate.

nacx · 2025-12-17T10:50:56Z

internal/controller/gateway_mutator_test.go

 					}

+					// Create Gateway and GatewayConfig for GatewayConfig test case
+					if tt.name == "with GatewayConfig" {


Instead of relying on the test name, which makes it harder to evolve these tests, just add a property to the test case: gatewayConfig *aigv1a1.GatewayConfig, and if it is set, then create it with the fake client. You can extract this GW config into a package variable to make it easier to reference in the test if most of its information is static.

nacx · 2025-12-17T10:52:48Z

tests/e2e/otel_tracing_test.go

+	require.True(t, ok, "failed to get source file path")
+	sourceDir := filepath.Dir(filename)
+
+	manifest := filepath.Join(sourceDir, "testdata", "otel_tracing_gateway_config.yaml")


Instead of doing this, delete this custom file and point directly to the file in the examples directory. This is what I meant in my previous comment. You already spotted an issue where the example was missing the kubernetes keyword, and we want to keep examples always working. Let's do that by using those in the e2e tests, as we do with other examples.

mathetake · 2025-12-21T23:30:13Z

@sqaisar would you mind addressing comments by @nacx? this is almost there to the finish line and we would love to see this land before the next v0.5 release!

sqaisar requested a review from a team as a code owner December 5, 2025 19:25

dosubot bot added the size:XXL This PR changes 1000+ lines, ignoring generated files. label Dec 5, 2025

sqaisar force-pushed the main branch 4 times, most recently from d26095e to 8984f5b Compare December 5, 2025 19:37

mathetake reviewed Dec 5, 2025

View reviewed changes

nacx reviewed Dec 6, 2025

View reviewed changes

api/v1alpha1/gateway_config.go Show resolved Hide resolved

sqaisar added 2 commits December 6, 2025 18:57

sqaisar force-pushed the main branch from c816ef1 to bc64bbe Compare December 6, 2025 13:57

mathetake mentioned this pull request Dec 6, 2025

feat: secretKeyRef support in extraProcEnvVars #1150

Closed

sqaisar and others added 2 commits December 7, 2025 18:34

refactor: GatewayConfigExtProc type to reuse the KubernetesContainerS…

c32bea9

…pec from the Envoy Gateway API Signed-off-by: Shabab Qaisar <[email protected]>

Merge branch 'main' into main

b6a0e41

mathetake reviewed Dec 8, 2025

View reviewed changes

api/v1alpha1/gateway_config.go Show resolved Hide resolved

sqaisar and others added 3 commits December 9, 2025 07:02

refactor: GatewayConfigExtProc type to utilize the KubernetesContaine…

c71a96b

…rSpec for defining the external processor's configuration. Signed-off-by: Shabab Qaisar <[email protected]>

Merge branch 'main' into main

77765ae

Signed-off-by: Shabab Qaisar <[email protected]>

fix: correct indentation in ApplyIndexing function in controller.go

883ffce

Signed-off-by: Shabab Qaisar <[email protected]>

mathetake reviewed Dec 9, 2025

View reviewed changes

api/v1alpha1/gateway_config.go Outdated Show resolved Hide resolved

mathetake reviewed Dec 9, 2025

View reviewed changes

internal/controller/controller.go Outdated Show resolved Hide resolved

mathetake reviewed Dec 9, 2025

View reviewed changes

internal/controller/gateway_mutator.go Show resolved Hide resolved

mathetake reviewed Dec 9, 2025

View reviewed changes

sqaisar added 2 commits December 9, 2025 10:04

refactor: Enhanced resource handling in gateway_mutator to prioritize…

4e5cc62

… GatewayConfig resources over route-scoped values. Signed-off-by: Shabab Qaisar <[email protected]>

Add unit tests for GatewayConfigController handling of missing config…

8b34fe7

…urations and list errors Signed-off-by: Shabab Qaisar <[email protected]>

mathetake approved these changes Dec 15, 2025

View reviewed changes

internal/controller/gateway_mutator.go Outdated Show resolved Hide resolved

mathetake self-assigned this Dec 15, 2025

sqaisar and others added 2 commits December 15, 2025 13:37

Update internal/controller/gateway_mutator.go

13b20cc

Co-authored-by: Takeshi Yoneda <[email protected]> Signed-off-by: Shabab Qaisar <[email protected]>

Merge branch 'main' into main

18f99cb

nacx reviewed Dec 16, 2025

View reviewed changes

internal/controller/gateway_config.go Outdated Show resolved Hide resolved

internal/controller/gateway_config_test.go Show resolved Hide resolved

internal/controller/gateway_mutator_test.go Show resolved Hide resolved

examples/gateway-config/comprehensive.yaml Show resolved Hide resolved

nacx linked an issue Dec 16, 2025 that may be closed by this pull request

How to achive tracing per gateway? #1552

Open

sqaisar and others added 2 commits December 17, 2025 12:44

Added a test manifest for OpenTelemetry tracing with GatewayConfig to…

57bab8a

… facilitate e2e testing Signed-off-by: Shabab Qaisar <[email protected]>

Merge branch 'main' into main

4901e49

Updated the to use for environment variables under .

0e5a3e0

Signed-off-by: Shabab Qaisar <[email protected]>

nacx reviewed Dec 17, 2025

View reviewed changes

mathetake assigned nacx Dec 18, 2025

feat: introduce GatewayConfig CRD for gateway-scoped configuration #1623

Are you sure you want to change the base?

feat: introduce GatewayConfig CRD for gateway-scoped configuration #1623

Conversation

sqaisar commented Dec 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Example

Uh oh!

mathetake left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

nacx left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

sqaisar commented Dec 6, 2025

Uh oh!

mathetake left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

sqaisar commented Dec 9, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mathetake left a comment

Choose a reason for hiding this comment

Uh oh!

sqaisar commented Dec 9, 2025

Uh oh!

codecov-commenter commented Dec 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

mathetake left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

sqaisar commented Dec 16, 2025

Uh oh!

Xunzhuo commented Dec 16, 2025

Uh oh!

nacx commented Dec 16, 2025

Uh oh!

nacx left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sqaisar commented Dec 17, 2025

Uh oh!

nacx Dec 17, 2025

Choose a reason for hiding this comment

Uh oh!

nacx Dec 17, 2025

Choose a reason for hiding this comment

Uh oh!

nacx Dec 17, 2025

Choose a reason for hiding this comment

Uh oh!

mathetake commented Dec 21, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

sqaisar commented Dec 5, 2025 •

edited

Loading

codecov-commenter commented Dec 9, 2025 •

edited

Loading

mathetake left a comment •

edited

Loading