envoyproxy · muwaqar-cflt · Jun 12, 2026 · Jun 12, 2026 · Jun 15, 2026 · Jun 15, 2026
@@ -186,6 +186,10 @@ jobs:
           ipFamily: ipv4
           profile: watch-namespaces
           gwapiChannel: experimental
+        - version: v1.36.1
+          ipFamily: ipv4
+          profile: merge-backends
+          gwapiChannel: experimental
     steps:
     - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
     - uses: ./tools/github-actions/setup-deps

@@ -35,6 +35,7 @@ type EnvoyProxy struct {
 }
 
 // EnvoyProxySpec defines the desired state of EnvoyProxy.
+// +kubebuilder:validation:XValidation:message="mergeGateways and mergeBackends cannot both be enabled",rule="!(has(self.mergeGateways) && self.mergeGateways && has(self.mergeBackends) && has(self.mergeBackends.enabled) && self.mergeBackends.enabled)"
 type EnvoyProxySpec struct {
 	// Provider defines the desired resource provider and provider-specific configuration.
 	// If unspecified, the "Kubernetes" resource provider is used with default configuration
@@ -89,9 +90,22 @@ type EnvoyProxySpec struct {
 	// This means that the port, protocol and hostname tuple must be unique for every listener.
 	// If a duplicate listener is detected, the newer listener (based on timestamp) will be rejected and its status will be updated with a "Accepted=False" condition.
 	//
+	// Mutually exclusive with MergeBackends.
+	//
 	// +optional
 	MergeGateways *bool `json:"mergeGateways,omitempty"`
 
+	// MergeBackends configures cluster deduplication: routes that reference the same backend
+	// share a single Envoy cluster instead of Envoy Gateway generating one cluster per route
+	// rule. This reduces xDS size, active health-check traffic, and stats cardinality, and
+	// improves upstream connection pooling.
+	//
+	// This is an experimental optimization and is disabled when unset. Mutually exclusive with
+	// MergeGateways.
+	//
+	// +optional
+	MergeBackends *MergeBackendsConfig `json:"mergeBackends,omitempty"`
+
 	// Shutdown defines configuration for graceful envoy shutdown process.
 	//
 	// +optional
@@ -218,6 +232,18 @@ type EnvoyProxySpec struct {
 	MergeType *MergeType `json:"mergeType,omitempty"`
 }
 
+// MergeBackendsConfig configures backend cluster deduplication (MergeBackends).
+type MergeBackendsConfig struct {
+	// Enabled toggles whether cluster deduplication is considered at all. Defaults to false.
+	//
+	// A backendRef is only merged into a shared cluster when safe to do so; otherwise it falls
+	// back to a dedicated per-route cluster.
+	//
+	// +optional
+	// +kubebuilder:default=false
+	Enabled *bool `json:"enabled,omitempty"`
+}
+
 // EnvoyProxyGeoIP defines shared GeoIP provider settings for EnvoyProxy.
 type EnvoyProxyGeoIP struct {
 	// Provider defines the GeoIP provider configuration used by GeoIP filter instances.

@@ -778,12 +778,33 @@ spec:
                 - InsecureSyntax
                 - Disabled
                 type: string
+              mergeBackends:
+                description: |-
+                  MergeBackends configures cluster deduplication: routes that reference the same backend
+                  share a single Envoy cluster instead of Envoy Gateway generating one cluster per route
+                  rule. This reduces xDS size, active health-check traffic, and stats cardinality, and
+                  improves upstream connection pooling.
+
+                  This is an experimental optimization and is disabled when unset. Mutually exclusive with
+                  MergeGateways.
+                properties:
+                  enabled:
+                    default: false
+                    description: |-
+                      Enabled toggles whether cluster deduplication is considered at all. Defaults to false.
+
+                      A backendRef is only merged into a shared cluster when safe to do so; otherwise it falls
+                      back to a dedicated per-route cluster.
+                    type: boolean
+                type: object
               mergeGateways:
                 description: |-
                   MergeGateways defines if Gateway resources should be merged onto the same Envoy Proxy Infrastructure.
                   Setting this field to true would merge all Gateway Listeners under the parent Gateway Class.
                   This means that the port, protocol and hostname tuple must be unique for every listener.
                   If a duplicate listener is detected, the newer listener (based on timestamp) will be rejected and its status will be updated with a "Accepted=False" condition.
+
+                  Mutually exclusive with MergeBackends.
                 type: boolean
               mergeType:
                 description: |-
@@ -18112,6 +18133,10 @@ spec:
                       rule: '!(has(self.samplingRate) && has(self.samplingFraction))'
                 type: object
             type: object
+            x-kubernetes-validations:
+            - message: mergeGateways and mergeBackends cannot both be enabled
+              rule: '!(has(self.mergeGateways) && self.mergeGateways && has(self.mergeBackends)
+                && has(self.mergeBackends.enabled) && self.mergeBackends.enabled)'
           status:
             description: EnvoyProxyStatus defines the actual state of EnvoyProxy.
             properties:

@@ -777,12 +777,33 @@ spec:
                 - InsecureSyntax
                 - Disabled
                 type: string
+              mergeBackends:
+                description: |-
+                  MergeBackends configures cluster deduplication: routes that reference the same backend
+                  share a single Envoy cluster instead of Envoy Gateway generating one cluster per route
+                  rule. This reduces xDS size, active health-check traffic, and stats cardinality, and
+                  improves upstream connection pooling.
+
+                  This is an experimental optimization and is disabled when unset. Mutually exclusive with
+                  MergeGateways.
+                properties:
+                  enabled:
+                    default: false
+                    description: |-
+                      Enabled toggles whether cluster deduplication is considered at all. Defaults to false.
+
+                      A backendRef is only merged into a shared cluster when safe to do so; otherwise it falls
+                      back to a dedicated per-route cluster.
+                    type: boolean
+                type: object
               mergeGateways:
                 description: |-
                   MergeGateways defines if Gateway resources should be merged onto the same Envoy Proxy Infrastructure.
                   Setting this field to true would merge all Gateway Listeners under the parent Gateway Class.
                   This means that the port, protocol and hostname tuple must be unique for every listener.
                   If a duplicate listener is detected, the newer listener (based on timestamp) will be rejected and its status will be updated with a "Accepted=False" condition.
+
+                  Mutually exclusive with MergeBackends.
                 type: boolean
               mergeType:
                 description: |-
@@ -18111,6 +18132,10 @@ spec:
                       rule: '!(has(self.samplingRate) && has(self.samplingFraction))'
                 type: object
             type: object
+            x-kubernetes-validations:
+            - message: mergeGateways and mergeBackends cannot both be enabled
+              rule: '!(has(self.mergeGateways) && self.mergeGateways && has(self.mergeBackends)
+                && has(self.mergeBackends.enabled) && self.mergeBackends.enabled)'
           status:
             description: EnvoyProxyStatus defines the actual state of EnvoyProxy.
             properties: