perf(xds): add opt-in endpoint fast path for EDS-only pushes

api/v1alpha1/envoygateway_helpers.go

@@ -173,6 +173,7 @@ func (e *EnvoyGateway) GetEnvoyProxyDefaultSpec() *EnvoyProxySpec {
 var defaultRuntimeFlags = map[RuntimeFlag]bool{
 	XDSNameSchemeV2:    false,
 	EndpointSliceIndex: true,
+	EndpointFastPath:   false,
 	EnvoyProxyPatch:    true,
 }
 

api/v1alpha1/envoygateway_types.go

@@ -170,7 +170,7 @@ type GatewayAPISettings struct {
 // RuntimeFlag defines a runtime flag used to guard breaking changes or risky experimental features in new Envoy Gateway releases.
 // A runtime flag may be enabled or disabled by default and can be toggled through the EnvoyGateway resource.
 // +enum
-// +kubebuilder:validation:Enum=XDSNameSchemeV2;EndpointSliceIndex;PerResourceSystemCASecret;EnvoyProxyPatch;ApplyClientTrafficPolicyHTTP1SettingsToClientsOnly
+// +kubebuilder:validation:Enum=XDSNameSchemeV2;EndpointSliceIndex;PerResourceSystemCASecret;EndpointFastPath;EnvoyProxyPatch;ApplyClientTrafficPolicyHTTP1SettingsToClientsOnly
 type RuntimeFlag string
 
 const (
@@ -192,6 +192,14 @@ const (
 	// it, which may cause a brief disruption to new connections on first enable.
 	PerResourceSystemCASecret RuntimeFlag = "PerResourceSystemCASecret" //nolint:gosec // not a credential
 
+	// EndpointFastPath enables propagating EndpointSlice updates to Envoy as EDS-only
+	// pushes without waiting for a full translation: endpoint changes are patched into
+	// the current xDS snapshot using cached per-cluster context from the last successful
+	// full translation. Endpoint changes that affect configuration (e.g. a backend's
+	// endpoint count crossing zero) still take the full path, and full translations
+	// remain authoritative. Disabled by default.
+	EndpointFastPath RuntimeFlag = "EndpointFastPath"
+
 	// EnvoyProxyPatch enables applying the Kubernetes resource `patch` fields configured on
 	// EnvoyProxy's Kubernetes provider settings. It is enabled by default to preserve
 	// pre-existing behavior. Because EnvoyProxy is commonly namespace-scoped and

internal/gatewayapi/resource/resource.go

@@ -183,6 +183,22 @@ func (c *ControllerResourcesContext) StoredAtTime() time.Time {
 	return c.StoredAt
 }
 
+// SortEndpointSlices sorts EndpointSlices by creation timestamp, then
+// namespace/name. It is shared with the provider's endpoint fast path
+// publisher, which must derive endpoints in the same order as a full
+// translation.
+func SortEndpointSlices(endpointSlices []*discoveryv1.EndpointSlice) {
+	sort.Slice(endpointSlices, func(i, j int) bool {
+		if endpointSlices[i].CreationTimestamp.Equal(&endpointSlices[j].CreationTimestamp) {
+			if endpointSlices[i].Namespace != endpointSlices[j].Namespace {
+				return endpointSlices[i].Namespace < endpointSlices[j].Namespace
+			}
+			return endpointSlices[i].Name < endpointSlices[j].Name
+		}
+		return endpointSlices[i].CreationTimestamp.Before(&endpointSlices[j].CreationTimestamp)
+	})
+}
+
 // DeepCopy creates a new ControllerResourcesContext.
 // The Context field is preserved (not deep copied) since contexts are meant to be passed around.
 func (c *ControllerResourcesContext) DeepCopy() *ControllerResourcesContext {
@@ -376,15 +392,7 @@ func (r *Resources) Sort() {
 	})
 
 	// Sort EndpointSlices by creation timestamp, then namespace/name
-	sort.Slice(r.EndpointSlices, func(i, j int) bool {
-		if r.EndpointSlices[i].CreationTimestamp.Equal(&r.EndpointSlices[j].CreationTimestamp) {
-			if r.EndpointSlices[i].Namespace != r.EndpointSlices[j].Namespace {
-				return r.EndpointSlices[i].Namespace < r.EndpointSlices[j].Namespace
-			}
-			return r.EndpointSlices[i].Name < r.EndpointSlices[j].Name
-		}
-		return r.EndpointSlices[i].CreationTimestamp.Before(&r.EndpointSlices[j].CreationTimestamp)
-	})
+	SortEndpointSlices(r.EndpointSlices)
 
 	// Sort Secrets by creation timestamp, then namespace/name
 	sort.Slice(r.Secrets, func(i, j int) bool {

internal/gatewayapi/route.go

@@ -30,6 +30,7 @@ import (
 	"github.com/envoyproxy/gateway/internal/gatewayapi/resource"
 	"github.com/envoyproxy/gateway/internal/gatewayapi/status"
 	"github.com/envoyproxy/gateway/internal/ir"
+	endpointsutil "github.com/envoyproxy/gateway/internal/utils/endpoints"
 	labelsutil "github.com/envoyproxy/gateway/internal/utils/labels"
 	"github.com/envoyproxy/gateway/internal/utils/regex"
 )
@@ -3051,9 +3052,10 @@ func (t *Translator) processServiceImportDestinationSetting(
 	btpRoutingType *egv1a1.RoutingType,
 ) (*ir.DestinationSetting, status.Error) {
 	var (
-		endpoints []*ir.DestinationEndpoint
-		addrType  *ir.DestinationAddressType
-		protocol  = defaultProtocol
+		endpoints      []*ir.DestinationEndpoint
+		addrType       *ir.DestinationAddressType
+		endpointSource *ir.EndpointSource
+		protocol       = defaultProtocol
 	)
 
 	serviceImport := t.GetServiceImport(backendNamespace, string(backendRef.Name))
@@ -3086,6 +3088,15 @@ func (t *Translator) processServiceImportDestinationSetting(
 				status.RouteReasonEndpointsNotFound,
 			)
 		}
+		if t.EndpointFastPathEnabled {
+			endpointSource = &ir.EndpointSource{
+				Kind:      resource.KindServiceImport,
+				Namespace: backendNamespace,
+				Name:      string(backendRef.Name),
+				PortName:  servicePort.Name,
+				Protocol:  getServicePortProtocol(servicePort.Protocol),
+			}
+		}
 	} else {
 		// Use ServiceImport IPs for routing
 		for _, ip := range backendIps {
@@ -3101,6 +3112,7 @@ func (t *Translator) processServiceImportDestinationSetting(
 		Endpoints:          endpoints,
 		AddressType:        addrType,
 		Metadata:           buildResourceMetadata(serviceImport, new(gwapiv1.SectionName(strconv.Itoa(int(*backendRef.Port))))),
+		EndpointSource:     endpointSource,
 	}, nil
 }
 
@@ -3113,8 +3125,9 @@ func (t *Translator) processServiceDestinationSetting(
 	btpRoutingType *egv1a1.RoutingType,
 ) (*ir.DestinationSetting, status.Error) {
 	var (
-		endpoints []*ir.DestinationEndpoint
-		addrType  *ir.DestinationAddressType
+		endpoints      []*ir.DestinationEndpoint
+		addrType       *ir.DestinationAddressType
+		endpointSource *ir.EndpointSource
 	)
 	protocol := defaultProtocol
 
@@ -3158,6 +3171,15 @@ func (t *Translator) processServiceDestinationSetting(
 				status.RouteReasonEndpointsNotFound,
 			)
 		}
+		if t.EndpointFastPathEnabled {
+			endpointSource = &ir.EndpointSource{
+				Kind:      KindDerefOr(backendRef.Kind, resource.KindService),
+				Namespace: backendNamespace,
+				Name:      string(backendRef.Name),
+				PortName:  servicePort.Name,
+				Protocol:  getServicePortProtocol(servicePort.Protocol),
+			}
+		}
 	} else {
 		// Use Service ClusterIP routing
 		ep := ir.NewDestEndpoint(nil, service.Spec.ClusterIP, uint32(*backendRef.Port), false, nil)
@@ -3172,6 +3194,7 @@ func (t *Translator) processServiceDestinationSetting(
 		AddressType:        addrType,
 		PreferLocal:        processPreferLocalZone(service),
 		Metadata:           buildResourceMetadata(service, new(gwapiv1.SectionName(strconv.Itoa(int(*backendRef.Port))))),
+		EndpointSource:     endpointSource,
 	}, nil
 }
 
@@ -3365,66 +3388,7 @@ func (t *Translator) processAllowedListenersForParentRefs(
 }
 
 func getIREndpointsFromEndpointSlices(endpointSlices []*discoveryv1.EndpointSlice, portName string, portProtocol corev1.Protocol) ([]*ir.DestinationEndpoint, *ir.DestinationAddressType) {
-	var (
-		dstEndpoints []*ir.DestinationEndpoint
-		dstAddrType  *ir.DestinationAddressType
-	)
-
-	addrTypeMap := make(map[ir.DestinationAddressType]int)
-	for _, endpointSlice := range endpointSlices {
-		if endpointSlice.AddressType == discoveryv1.AddressTypeFQDN {
-			addrTypeMap[ir.FQDN]++
-		} else {
-			addrTypeMap[ir.IP]++
-		}
-		endpoints := getIREndpointsFromEndpointSlice(endpointSlice, portName, portProtocol)
-		dstEndpoints = append(dstEndpoints, endpoints...)
-	}
-
-	for addrTypeState, addrTypeCounts := range addrTypeMap {
-		if addrTypeCounts == len(endpointSlices) {
-			dstAddrType = new(addrTypeState)
-			break
-		}
-	}
-
-	if len(addrTypeMap) > 0 && dstAddrType == nil {
-		dstAddrType = new(ir.MIXED)
-	}
-
-	return dstEndpoints, dstAddrType
-}
-
-func getIREndpointsFromEndpointSlice(endpointSlice *discoveryv1.EndpointSlice, portName string, portProtocol corev1.Protocol) []*ir.DestinationEndpoint {
-	var endpoints []*ir.DestinationEndpoint
-	for _, endpoint := range endpointSlice.Endpoints {
-		for _, endpointPort := range endpointSlice.Ports {
-			// Check if the endpoint port matches the service port
-			if *endpointPort.Name != portName || *endpointPort.Protocol != portProtocol {
-				continue
-			}
-			conditions := endpoint.Conditions
-
-			// Unknown Serving/Terminating (nil) should fall-back to Ready, see https://pkg.go.dev/k8s.io/api/discovery/v1#EndpointConditions
-			// So drain the endpoint if:
-			// 1. Both `Terminating` and `Serving` are != null, and either `Terminating=true` or `Serving=false`
-			// 2. Or `Ready=false`
-			var draining bool
-			if conditions.Serving != nil && conditions.Terminating != nil {
-				draining = *conditions.Terminating || !*conditions.Serving
-			} else {
-				draining = conditions.Ready != nil && !*conditions.Ready
-			}
-
-			for _, address := range endpoint.Addresses {
-				ep := ir.NewDestEndpoint(nil, address, uint32(*endpointPort.Port), draining, endpoint.Zone)
-				endpoints = append(endpoints, ep)
-			}
-
-		}
-	}
-
-	return endpoints
+	return endpointsutil.EndpointsFromSlices(endpointSlices, portName, portProtocol)
 }
 
 // isCustomBackendResource checks if the given group and kind match any of the configured custom backend resources

internal/gatewayapi/runner/runner.go

@@ -331,6 +331,7 @@ func (r *Runner) subscribeAndTranslate(sub <-chan watchable.Snapshot[string, *re
 					MergeGateways:                   gatewayapi.IsMergeGatewaysEnabled(resources),
 					MergeBackends:                   gatewayapi.ResolveMergeBackendsConfig(resources),
 					PerResourceSystemCASecret:       r.EnvoyGateway.RuntimeFlags.IsEnabled(egv1a1.PerResourceSystemCASecret),
+					EndpointFastPathEnabled:         r.EnvoyGateway.RuntimeFlags.IsEnabled(egv1a1.EndpointFastPath),
 					WasmCache:                       r.wasmCache,
 					RunningOnHost:                   r.EnvoyGateway.Provider != nil && r.EnvoyGateway.Provider.IsRunningOnHost(),
 					InfraRemotelyManaged:            r.EnvoyGateway.Provider != nil && r.EnvoyGateway.Provider.IsInfraManagedRemotely(),

internal/gatewayapi/translator.go

@@ -140,6 +140,11 @@ type Translator struct {
 	// sharing a single system_ca_certificates secret. Disabled by default (shared secret used).
 	PerResourceSystemCASecret bool
 
+	// EndpointFastPathEnabled records the endpoint source on EndpointSlice-backed
+	// destination settings so the xDS runner can re-resolve endpoint updates
+	// without a full translation.
+	EndpointFastPathEnabled bool
+
 	// GatewayNamespaceMode is true if controller uses gateway namespace mode for infra deployments.
 	GatewayNamespaceMode bool
 

internal/ir/xds.go

@@ -2502,6 +2502,28 @@ type DestinationSetting struct {
 	// * invalid 500
 	// * without endpoints 503
 	Invalid bool `json:"invalid,omitempty" yaml:"invalid,omitempty"`
+	// EndpointSource identifies the Kubernetes backend this setting's endpoints are
+	// derived from, so endpoint updates can be re-resolved without a full translation.
+	// Only set for EndpointSlice-backed (EDS) settings when the EndpointFastPath
+	// runtime flag is enabled.
+	EndpointSource *EndpointSource `json:"endpointSource,omitempty" yaml:"endpointSource,omitempty"`
+}
+
+// EndpointSource identifies the Kubernetes backend an EDS-managed DestinationSetting's
+// endpoints are derived from, along with the parameters needed to filter that backend's
+// EndpointSlices the same way the full translation does.
+// +kubebuilder:object:generate=true
+type EndpointSource struct {
+	// Kind is the backend kind: Service or ServiceImport.
+	Kind string `json:"kind" yaml:"kind"`
+	// Namespace of the backend.
+	Namespace string `json:"namespace" yaml:"namespace"`
+	// Name of the backend.
+	Name string `json:"name" yaml:"name"`
+	// PortName is the service port name used to filter EndpointSlice ports.
+	PortName string `json:"portName,omitempty" yaml:"portName,omitempty"`
+	// Protocol is the service port protocol used to filter EndpointSlice ports.
+	Protocol corev1.Protocol `json:"protocol,omitempty" yaml:"protocol,omitempty"`
 }
 
 // Validate the fields within the DestinationSetting structure