feat: Add EnvoyProxyTemplate for global Envoy Proxy defaults by mgs255 · Pull Request #7698 · envoyproxy/gateway

mgs255 · 2025-12-08T10:24:32Z

Introduce EnvoyProxy default configuration

Add a new envoyProxy field to the EnvoyGateway spec to support cluster-wide shared defaults. This defines a three-level hierarchy for EnvoyProxy configuration (highest to lowest priority):

Gateway-level EnvoyProxy (via Gateway.spec.infrastructure.parametersRef)
GatewayClass-level EnvoyProxy (via GatewayClass.spec.parametersRef)
EnvoyProxy defaults on EnvoyGateway

Currently uses replace semantics where the most specific configuration wins completely. The default spec is almost completely redundant in the sense that it gets completely replaced by any more specific configuration - but this establishes the foundation for a future PR that will add a MergeType to enable merging configurations across levels.

Towards #4764

Signed-off-by: Michael Sommerville msommerville@gmail.com

api/v1alpha1/envoygateway_types.go

codecov · 2025-12-10T18:06:27Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 73.78%. Comparing base (626a08a) to head (fa0a115).
⚠️ Report is 29 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #7698      +/-   ##
==========================================
+ Coverage   73.52%   73.78%   +0.26%     
==========================================
  Files         237      237              
  Lines       35653    35767     +114     
==========================================
+ Hits        26214    26392     +178     
+ Misses       7576     7518      -58     
+ Partials     1863     1857       -6

☔ 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.

charts/gateway-helm/values.tmpl.yaml

api/v1alpha1/shared_types.go

internal/infrastructure/kubernetes/proxy/resource_provider.go

.gitignore

arkodg · 2025-12-19T04:18:03Z

api/v1alpha1/shared_types.go

@@ -180,8 +180,10 @@ type KubernetesPodSpec struct {
 	// Volumes that can be mounted by containers belonging to the pod.
 	// More info: https://kubernetes.io/docs/concepts/storage/volumes
 	//
+	// +patchMergeKey=name
+	// +patchStrategy=merge


thanks, can you also add these for ImagePullSecrets , TopologySpreadConstraints, InitContainers and all other slices in EnvoyProxy

arkodg · 2025-12-19T04:23:11Z

internal/gatewayapi/envoyproxy_merge.go

+	"github.com/envoyproxy/gateway/internal/utils"
+)
+
+// MergeEnvoyProxyConfigs merges EnvoyProxy configurations using a 3-level hierarchy:


this changes the spec
3. completely replaces 2. today, there is no merge

so 1. would either merge with 3. if it exists or merge with 2. if 3. is absent

Yes you are right. The original version only did the merge if the template was present. See below.

arkodg · 2025-12-19T04:25:48Z

api/v1alpha1/envoygateway_types.go

+	// (e.g., env vars, volumes) are combined from both sources.
+	//
+	// +optional
+	EnvoyProxyTemplate *EnvoyProxySpec `json:"envoyProxyTemplate,omitempty"`


we may want create a new struct type and embed EnvoyProxySpec which allows us to add a mergeType or something similar to highlight how this will get merged

To preserve backward compatibility, added a new EnvoyProxyTemplateSpec struct with a mergeType option - where Replace is the default.

@arkodg Would you be able to give this another once over? It would be great to get this in.

sorry for the delay, reviewing rn

netlify · 2026-01-08T15:11:13Z

✅ Deploy Preview for cerulean-figolla-1f9435 canceled.

Name	Link
🔨 Latest commit	`fa0a115`
🔍 Latest deploy log	https://app.netlify.com/projects/cerulean-figolla-1f9435/deploys/69777b652382420008adb41e

arkodg · 2026-01-11T04:05:55Z

api/v1alpha1/envoygateway_types.go

+	// with or replace template definitions based on the mergeType.
+	//
+	// +optional
+	EnvoyProxyTemplate *EnvoyProxyTemplateSpec `json:"envoyProxyTemplate,omitempty"`


should this be EnvoyProxyTemplate or EnvoyProxy
@envoyproxy/gateway-maintainers

(lets time box this to a week to avoid more delay for this PR)

arkodg · 2026-01-11T04:07:56Z

api/v1alpha1/envoygateway_types.go

+	//
+	// +optional
+	// +kubebuilder:default=Replace
+	MergeType *EnvoyProxyTemplateMergeType `json:"mergeType,omitempty"`


for the BackendTrafficPolicy case, the child policy specifies the MergeType and defaults to Replace, right now in this case the parent has this setting, should we move this to the EnvoyProxy resource ?
@envoyproxy/gateway-maintainers

there's some dicussion in the past here.

We chatted about this in the community meeting. I'm a +1 on moving MergeType into EnvoyProxy and using that in EnvoyGateway too so we can define the merge behavior in all layers.

yeah piggybacking based on what Isaac said, we can split this work into 2 parts/PRs

Introduce EnvoyProxy *EnvoyProxySpec in EnvoyGateway and use the same replace semantics we have for deciding what EnvoyProxy wins

Later introduce MergeType into EnvoyProxySpec and deal with multi level merge

sorry for the churn @mgs255, hope this adds more clarity

@arkodg Yes, sounds reasonable but does that work in practice?

The way I've installed this in our environments, we have all of the configuration defined centrally in the helm values file. There is large envoyProxyTemplate e.g:

# Lots above.... rateLimitHpa: minReplicas: 2 maxReplicas: 10 metrics: - type: Resource resource: name: cpu target: type: Utilization averageUtilization: 60 envoyProxyTemplate: mergeType: StrategicMerge spec: mergeGateways: true logging: level: default: info config: info upstream: info jwt: info oauth2: info http: info filter: info router: info connection: info provider: kubernetes: envoyHpa: minReplicas: 2 maxReplicas: 10 metrics: - type: Resource resource: name: cpu target: type: Utilization averageUtilization: 60 # Lots more below.... ...

We also a minimal EnvoyProxy object in each target cluster using the following template in a different helm chart:

apiVersion: gateway.envoyproxy.io/v1alpha1 kind: EnvoyProxy metadata: name: {{ .Values.proxyName }} namespace: {{ .Release.Namespace }} labels: {{- include "pulse-envoy-aws-gateway.labels" . | nindent 4 }} # Ideally we would not set any properties here and just let the template override everything - unfortunately # a complete empty spec (even {} or null) appears invalid spec: logging: level: default: {{ .Values.logging.level.proxy }}

If we only supported the replace option initially then the most specific EnvoyProxy would completely replace the values from the template, right?

yeah just suggesting the 2 step approach to increase the velocity of code review and getting something in, but agree when merge lands, thats when your use cases and more powerful use cases will be unlocked

hey @mgs255 would be great if we can get part 1 into v1.7.0-rc.1 (deadline is 01/28)

Ok - re-done based on those comments. I will work on some further changes to also add the mergeType and start testing this in our environments.

arkodg · 2026-01-11T04:09:05Z

hey have some open questions here @mgs255, will raise these in the community meeting next week and get them resolved

Add a new envoyProxy field to the EnvoyGateway spec to support cluster-wide shared defaults. This defines a three-level hierarchy for EnvoyProxy configuration (highest to lowest priority): 1. Gateway-level EnvoyProxy (via Gateway.spec.infrastructure.parametersRef) 2. GatewayClass-level EnvoyProxy (via GatewayClass.spec.parametersRef) 3. EnvoyProxy defaults on EnvoyGateway Currently uses replace semantics where the most specific configuration wins completely. The default spec is almost completely redundant in the sense that it gets completely replaced by any more specific configuration - but this establishes the foundation for a future PR that will add a MergeType to enable merging configurations across levels. Towards envoyproxy#4764 Signed-off-by: Michael Sommerville <msommerville@gmail.com>

Signed-off-by: Michael Sommerville <msommerville@gmail.com>

zirain

LGTM, it would be good to add some e2e for this with following PR.

e.g. add a dummy/valid EnvoyProxy in test/config/envoy-gateaway-config/default.yaml and the one referenced by GatewayClass will override it, e2e should all pass.

arkodg · 2026-01-24T18:00:51Z

thanks, LGTM, +1 to zirain's comments around add some tests

Signed-off-by: Michael Sommerville <msommerville@gmail.com>

zirain

LGTM, thanks!

zirain · 2026-01-28T04:47:33Z

One thing could be imrpove in the next is adding another test case by adding a new GC and it shouldn’t be provision correctly because of the invalid image.

zirain · 2026-01-28T14:22:50Z

no sure what happen, but this cause e2e always failed on dual+default.

mgs255 · 2026-01-28T22:13:17Z

That is really odd. It must be related to the addition in contexts.go. I'll open a new branch removing that section.

I'm having a real problem trying to run the e2e tests locally on Mac though so it is a pain to debug this.

@arkodg @zirain I've pushed a branch which should completely disable that defaulting behaviour for now.

#8103

…oxy#7698) * Introduce EnvoyProxy default configuration Add a new envoyProxy field to the EnvoyGateway spec to support cluster-wide shared defaults. This defines a three-level hierarchy for EnvoyProxy configuration (highest to lowest priority): 1. Gateway-level EnvoyProxy (via Gateway.spec.infrastructure.parametersRef) 2. GatewayClass-level EnvoyProxy (via GatewayClass.spec.parametersRef) 3. EnvoyProxy defaults on EnvoyGateway Currently uses replace semantics where the most specific configuration wins completely. The default spec is almost completely redundant in the sense that it gets completely replaced by any more specific configuration - but this establishes the foundation for a future PR that will add a MergeType to enable merging configurations across levels. Towards envoyproxy#4764 Signed-off-by: Michael Sommerville <msommerville@gmail.com> Signed-off-by: Sadmi Bouhafs <sadmibouhafs@gmail.com>

ion-elgreco · 2026-03-03T10:34:10Z

Just wanted to say thanks for adding this! :) It simplified all my deployments a lot 🫡

mgs255 force-pushed the allow-provide-default-proxy-image branch 2 times, most recently from 7da24bf to 02beef5 Compare December 8, 2025 10:56

zirain reviewed Dec 8, 2025

View reviewed changes

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

mgs255 force-pushed the allow-provide-default-proxy-image branch 3 times, most recently from fd2a520 to 0ae8e1d Compare December 10, 2025 17:21

mgs255 marked this pull request as ready for review December 10, 2025 17:26

mgs255 requested a review from a team as a code owner December 10, 2025 17:26

zirain reviewed Dec 11, 2025

View reviewed changes

charts/gateway-helm/values.tmpl.yaml Outdated Show resolved Hide resolved

arkodg reviewed Dec 11, 2025

View reviewed changes

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

arkodg reviewed Dec 11, 2025

View reviewed changes

internal/infrastructure/kubernetes/proxy/resource_provider.go Outdated Show resolved Hide resolved

mgs255 force-pushed the allow-provide-default-proxy-image branch from 0ae8e1d to 804ff4b Compare December 15, 2025 07:45

mgs255 marked this pull request as draft December 15, 2025 07:46

mgs255 force-pushed the allow-provide-default-proxy-image branch 4 times, most recently from 23b261c to ff220ab Compare December 16, 2025 18:16

mgs255 marked this pull request as ready for review December 16, 2025 18:22

mgs255 force-pushed the allow-provide-default-proxy-image branch 3 times, most recently from e5283b6 to c198efe Compare December 17, 2025 11:51

mgs255 requested review from arkodg, jukie and zirain December 18, 2025 13:27

arkodg reviewed Dec 19, 2025

View reviewed changes

.gitignore Outdated Show resolved Hide resolved

arkodg reviewed Dec 19, 2025

View reviewed changes

mgs255 force-pushed the allow-provide-default-proxy-image branch from dd0a4dc to 67f0b55 Compare December 23, 2025 10:23

zirain previously approved these changes Dec 30, 2025

View reviewed changes

arkodg reviewed Jan 11, 2026

View reviewed changes

mgs255 dismissed zirain’s stale review via 6adea4a January 22, 2026 18:14

mgs255 force-pushed the allow-provide-default-proxy-image branch from f709f2e to 6adea4a Compare January 22, 2026 18:14

mgs255 force-pushed the allow-provide-default-proxy-image branch from 6adea4a to 5d64148 Compare January 22, 2026 18:16

mgs255 requested review from arkodg and zirain January 22, 2026 18:20

Fix formatting

1ef2f21

Signed-off-by: Michael Sommerville <msommerville@gmail.com>

zirain previously approved these changes Jan 24, 2026

View reviewed changes

arkodg added this to the v1.7.0-rc.1 Release milestone Jan 24, 2026

arkodg mentioned this pull request Jan 25, 2026

Feat/4764 envoyproxy infra helm #8041

Closed

mgs255 dismissed zirain’s stale review via e246274 January 26, 2026 14:32

Update default envoy-gateway-config with (unused) envoyProxy override

fa0a115

Signed-off-by: Michael Sommerville <msommerville@gmail.com>

mgs255 force-pushed the allow-provide-default-proxy-image branch from e246274 to fa0a115 Compare January 26, 2026 14:34

zirain approved these changes Jan 26, 2026

View reviewed changes

arkodg approved these changes Jan 28, 2026

View reviewed changes

arkodg merged commit cf54ff9 into envoyproxy:main Jan 28, 2026
51 of 60 checks passed

zirain mentioned this pull request Jan 28, 2026

chore: fix invalid EnvoyProxy #8090

Closed

Conversation

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

Uh oh!

Uh oh!

Uh oh!

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

Uh oh!

Codecov Report

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

arkodg Dec 19, 2025 • 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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

netlify bot commented Jan 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for cerulean-figolla-1f9435 canceled.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

arkodg commented Jan 11, 2026

Uh oh!

zirain left a comment

Choose a reason for hiding this comment

Uh oh!

arkodg commented Jan 24, 2026

Uh oh!

zirain left a comment

Choose a reason for hiding this comment

Uh oh!

zirain commented Jan 28, 2026

Uh oh!

Uh oh!

zirain commented Jan 28, 2026

Uh oh!

mgs255 commented Jan 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ion-elgreco commented Mar 3, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

mgs255 commented Dec 8, 2025 •

edited

Loading

codecov bot commented Dec 10, 2025 •

edited

Loading

arkodg Dec 19, 2025 •

edited

Loading

netlify bot commented Jan 8, 2026 •

edited

Loading

mgs255 commented Jan 28, 2026 •

edited

Loading