api: add zoneAware lb config

api/v1alpha1/loadbalancer_types.go

@@ -12,6 +12,7 @@ import metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
 //
 // +kubebuilder:validation:XValidation:rule="self.type == 'ConsistentHash' ? has(self.consistentHash) : !has(self.consistentHash)",message="If LoadBalancer type is consistentHash, consistentHash field needs to be set."
 // +kubebuilder:validation:XValidation:rule="self.type in ['Random', 'ConsistentHash'] ? !has(self.slowStart) : true ",message="Currently SlowStart is only supported for RoundRobin and LeastRequest load balancers."
+// +kubebuilder:validation:XValidation:rule="self.type == 'ConsistentHash' ? !has(self.zoneAware) : true ",message="Currently ZoneAware is only supported for LeastRequest, Random, and RoundRobin load balancers."
 type LoadBalancer struct {
 	// Type decides the type of Load Balancer policy.
 	// Valid LoadBalancerType values are
@@ -34,6 +35,12 @@ type LoadBalancer struct {
 	//
 	// +optional
 	SlowStart *SlowStart `json:"slowStart,omitempty"`
+
+	// ZoneAware defines the configuration related to the distribution of requests between locality zones.
+	//
+	// +optional
+	// +notImplementedHide
+	ZoneAware *ZoneAware `json:"zoneAware,omitempty"`
 }
 
 // LoadBalancerType specifies the types of LoadBalancer.
@@ -135,3 +142,39 @@ type SlowStart struct {
 	Window *metav1.Duration `json:"window"`
 	// TODO: Add support for non-linear traffic increases based on user usage.
 }
+
+// ZoneAware defines the configuration related to the distribution of requests between locality zones.
+type ZoneAware struct {
+	// PreferLocalZone configures zone-aware routing to prefer sending traffic to the local locality zone.
+	//
+	// +optional
+	// +notImplementedHide
+	PreferLocal *PreferLocalZone `json:"preferLocal,omitempty"`
+}
+
+// PreferLocalZone configures zone-aware routing to prefer sending traffic to the local locality zone.
+type PreferLocalZone struct {
+	// ForceLocalZone defines override configuration for forcing all traffic to stay within the local zone instead of the default behavior
+	// which maintains equal distribution among upstream endpoints while sending as much traffic as possible locally.
+	//
+	// +optional
+	// +notImplementedHide
+	Force *ForceLocalZone `json:"force,omitempty"`
+
+	// MinEndpointsThreshold is the minimum number of total upstream endpoints across all zones required to enable zone-aware routing.
+	//
+	// +optional
+	// +notImplementedHide
+	MinEndpointsThreshold *uint64 `json:"minEndpointsCount,omitempty"`
+}
+
+// ForceLocalZone defines override configuration for forcing all traffic to stay within the local zone instead of the default behavior
+// which maintains equal distribution among upstream endpoints while sending as much traffic as possible locally.
+type ForceLocalZone struct {
+	// MinEndpointsInZoneThreshold is the minimum number of upstream endpoints in the local zone required to honor the forceLocalZone
+	// override. This is useful for protecting zones with fewer endpoints.
+	//
+	// +optional
+	// +notImplementedHide
+	MinEndpointsInZoneThreshold *uint32 `json:"minEndpointsInZoneThreshold,omitempty"`
+}

charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_backendtrafficpolicies.yaml

@@ -691,6 +691,34 @@ spec:
                     - Random
                     - RoundRobin
                     type: string
+                  zoneAware:
+                    description: ZoneAware defines the configuration related to the
+                      distribution of requests between locality zones.
+                    properties:
+                      preferLocal:
+                        description: PreferLocalZone configures zone-aware routing
+                          to prefer sending traffic to the local locality zone.
+                        properties:
+                          force:
+                            description: |-
+                              ForceLocalZone defines override configuration for forcing all traffic to stay within the local zone instead of the default behavior
+                              which maintains equal distribution among upstream endpoints while sending as much traffic as possible locally.
+                            properties:
+                              minEndpointsInZoneThreshold:
+                                description: |-
+                                  MinEndpointsInZoneThreshold is the minimum number of upstream endpoints in the local zone required to honor the forceLocalZone
+                                  override. This is useful for protecting zones with fewer endpoints.
+                                format: int32
+                                type: integer
+                            type: object
+                          minEndpointsCount:
+                            description: MinEndpointsThreshold is the minimum number
+                              of total upstream endpoints across all zones required
+                              to enable zone-aware routing.
+                            format: int64
+                            type: integer
+                        type: object
+                    type: object
                 required:
                 - type
                 type: object
@@ -703,6 +731,10 @@ spec:
                     LeastRequest load balancers.
                   rule: 'self.type in [''Random'', ''ConsistentHash''] ? !has(self.slowStart)
                     : true '
+                - message: Currently ZoneAware is only supported for LeastRequest,
+                    Random, and RoundRobin load balancers.
+                  rule: 'self.type == ''ConsistentHash'' ? !has(self.zoneAware) :
+                    true '
               mergeType:
                 description: |-
                   MergeType determines how this configuration is merged with existing BackendTrafficPolicy

charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_envoyextensionpolicies.yaml

@@ -769,6 +769,35 @@ spec:
                               - Random
                               - RoundRobin
                               type: string
+                            zoneAware:
+                              description: ZoneAware defines the configuration related
+                                to the distribution of requests between locality zones.
+                              properties:
+                                preferLocal:
+                                  description: PreferLocalZone configures zone-aware
+                                    routing to prefer sending traffic to the local
+                                    locality zone.
+                                  properties:
+                                    force:
+                                      description: |-
+                                        ForceLocalZone defines override configuration for forcing all traffic to stay within the local zone instead of the default behavior
+                                        which maintains equal distribution among upstream endpoints while sending as much traffic as possible locally.
+                                      properties:
+                                        minEndpointsInZoneThreshold:
+                                          description: |-
+                                            MinEndpointsInZoneThreshold is the minimum number of upstream endpoints in the local zone required to honor the forceLocalZone
+                                            override. This is useful for protecting zones with fewer endpoints.
+                                          format: int32
+                                          type: integer
+                                      type: object
+                                    minEndpointsCount:
+                                      description: MinEndpointsThreshold is the minimum
+                                        number of total upstream endpoints across
+                                        all zones required to enable zone-aware routing.
+                                      format: int64
+                                      type: integer
+                                  type: object
+                              type: object
                           required:
                           - type
                           type: object
@@ -781,6 +810,10 @@ spec:
                               and LeastRequest load balancers.
                             rule: 'self.type in [''Random'', ''ConsistentHash''] ?
                               !has(self.slowStart) : true '
+                          - message: Currently ZoneAware is only supported for LeastRequest,
+                              Random, and RoundRobin load balancers.
+                            rule: 'self.type == ''ConsistentHash'' ? !has(self.zoneAware)
+                              : true '
                         proxyProtocol:
                           description: ProxyProtocol enables the Proxy Protocol when
                             communicating with the backend.