KEP-3015 PreferSameNode TrafficDistribution 1.33 (#49943)

* Update TrafficDistribution docs for 1.33

* Update TrafficDistribution/TopologyAwareHints docs for GA

* Update for PreferSameTrafficDistribution

Author: danwinship

content/en/docs/concepts/services-networking/service.md

@@ -983,20 +983,25 @@ The `.spec.trafficDistribution` field provides another way to influence traffic
 routing within a Kubernetes Service. While traffic policies focus on strict
 semantic guarantees, traffic distribution allows you to express _preferences_
 (such as routing to topologically closer endpoints). This can help optimize for
-performance, cost, or reliability. This optional field can be used if you have
-enabled the `ServiceTrafficDistribution` [feature
-gate](/docs/reference/command-line-tools-reference/feature-gates/) for your
-cluster and all of its nodes. In Kubernetes {{< skew currentVersion >}}, the
+performance, cost, or reliability. In Kubernetes {{< skew currentVersion >}}, the
 following field value is supported: 
 
 `PreferClose`
-: Indicates a preference for routing traffic to endpoints that are topologically
-  proximate to the client. The interpretation of "topologically proximate" may
-  vary across implementations and could encompass endpoints within the same
-  node, rack, zone, or even region. Setting this value gives implementations
-  permission to make different tradeoffs, e.g. optimizing for proximity rather
-  than equal distribution of load. Users should not set this value if such
-  tradeoffs are not acceptable.
+: Indicates a preference for routing traffic to endpoints that are in the same
+  zone as the client.
+
+{{< feature-state feature_gate_name="PreferSameTrafficDistribution" >}}
+
+Two additional values are available when the `PreferSameTrafficDistribution`
+[feature gate](/docs/reference/command-line-tools-reference/feature-gates/) is
+enabled:
+
+`PreferSameZone`
+: This is an alias for `PreferClose` that is clearer about the intended semantics.
+
+`PreferSameNode`
+: Indicates a preference for routing traffic to endpoints that are on the same
+  node as the client.
 
 If the field is not set, the implementation will apply its default routing strategy.
 

content/en/docs/reference/command-line-tools-reference/feature-gates/PreferSameTrafficDistribution.md

@@ -0,0 +1,16 @@
+---
+title: PreferSameTrafficDistribution
+content_type: feature_gate
+
+_build:
+  list: never
+  render: false
+
+stages:
+- stage: alpha 
+  defaultValue: false
+  fromVersion: "1.33"
+---
+Allows usage of the values `PreferSameZone` and `PreferSameNode` in
+the Service [`trafficDistribution`](/docs/reference/networking/virtual-ips/#traffic-distribution)
+field.

content/en/docs/reference/command-line-tools-reference/feature-gates/ServiceTrafficDistribution.md

@@ -14,6 +14,10 @@ stages:
 - stage: beta
   defaultValue: true
   fromVersion: "1.31"
+  toVersion: "1.32"
+- stage: stable
+  defaultValue: true
+  fromVersion: "1.33"
 ---
 Allows usage of the optional `spec.trafficDistribution` field in Services. The
 field offers a way to express preferences for how traffic is distributed to

content/en/docs/reference/command-line-tools-reference/feature-gates/TopologyAwareHints.md

@@ -17,6 +17,10 @@ stages:
   - stage: beta
     defaultValue: true
     fromVersion: "1.24"
+    toVersion: "1.32"
+  - stage: stable
+    defaultValue: true
+    fromVersion: "1.33"
 ---
 Enables topology aware routing based on topology hints
 in EndpointSlices. See [Topology Aware

content/en/docs/reference/networking/virtual-ips.md

@@ -684,39 +684,57 @@ pool.
 
 The `spec.trafficDistribution` field within a Kubernetes Service allows you to
 express preferences for how traffic should be routed to Service endpoints.
-Implementations like kube-proxy use the `spec.trafficDistribution` field as a
-guideline. The behavior associated with a given preference may subtly differ
-between implementations.
 
-`PreferClose` with kube-proxy
-: For kube-proxy, this means prioritizing sending traffic to endpoints within
-  the same zone as the client. The EndpointSlice controller updates
-  EndpointSlices with `hints` to communicate this preference, which kube-proxy
-  then uses for routing decisions. If a client's zone does not have any
-  available endpoints, traffic will be routed cluster-wide for that client.
-
-In the absence of any value for `trafficDistribution`, the default routing
-strategy for kube-proxy is to distribute traffic to any endpoint in the cluster.
+`PreferClose`
+: This prioritizes sending traffic to endpoints in the same zone as the client.
+  The EndpointSlice controller updates EndpointSlices with `hints` to
+  communicate this preference, which kube-proxy then uses for routing decisions.
+  If a client's zone does not have any available endpoints, traffic will be
+  routed cluster-wide for that client.
+
+{{< feature-state feature_gate_name="PreferSameTrafficDistribution" >}}
+
+Two additional values are available when the `PreferSameTrafficDistribution`
+[feature gate](/docs/reference/command-line-tools-reference/feature-gates/) is
+enabled:
+
+`PreferSameZone`
+: This means the same thing as `PreferClose`, but is more explicit. (Originally,
+  the intention was that `PreferClose` might later include functionality other
+  than just "prefer same zone", but this is no longer planned. In the future,
+  `PreferSameZone` will be the recommended value to use for this functionality,
+  and `PreferClose` will be considered a deprecated alias for it.)
+
+`PreferSameNode`
+: This prioritizes sending traffic to endpoints on the same node as the client.
+  As with `PreferClose`/`PreferSameZone`, the EndpointSlice controller updates
+  EndpointSlices with `hints` indicating that a slice should be used for a
+  particular node. If a client's node does not have any available endpoints,
+  then the service proxy will fall back to "same zone" behavior, or cluster-wide
+  if there are no same-zone endpoints either.
+
+In the absence of any value for `trafficDistribution`, the default strategy is
+to distribute traffic evenly to all endpoints in the cluster.
 
 ### Comparison with `service.kubernetes.io/topology-mode: Auto`
 
-The `trafficDistribution` field with `PreferClose` and the
-`service.kubernetes.io/topology-mode: Auto` annotation both aim to prioritize
-same-zone traffic. However, there are key differences in their approaches:
+The `trafficDistribution` field with `PreferClose`/`PreferSameZone`, and the older "Topology-Aware
+Routing" feature using the `service.kubernetes.io/topology-mode: Auto`
+annotation both aim to prioritize same-zone traffic. However, there is a key
+difference in their approaches:
 
-* `service.kubernetes.io/topology-mode: Auto`: Attempts to distribute traffic
+* `service.kubernetes.io/topology-mode: Auto` attempts to distribute traffic
   proportionally across zones based on allocatable CPU resources. This heuristic
   includes safeguards (such as the [fallback
   behavior](/docs/concepts/services-networking/topology-aware-routing/#three-or-more-endpoints-per-zone)
-  for small numbers of endpoints) and could lead to the feature being disabled
-  in certain scenarios for load-balancing reasons. This approach sacrifices some
-  predictability in favor of potential load balancing.
-
-* `trafficDistribution: PreferClose`: This approach aims to be slightly simpler
-  and more predictable: "If there are endpoints in the zone, they will receive
-  all traffic for that zone, if there are no endpoints in a zone, the traffic
-  will be distributed to other zones". While the approach may offer more
-  predictability, it does mean that you are in control of managing a [potential
+  for small numbers of endpoints), sacrificing some predictability in favor of
+  potentially better load balancing.
+
+* `trafficDistribution: PreferClose` aims to be simpler and more predictable:
+  "If there are endpoints in the zone, they will receive all traffic for that
+  zone, if there are no endpoints in a zone, the traffic will be distributed to
+  other zones". This approach offers more predictability, but it means that you
+  are responsible for [avoiding endpoint
   overload](#considerations-for-using-traffic-distribution-control).
 
 If the `service.kubernetes.io/topology-mode` annotation is set to `Auto`, it
@@ -732,41 +750,38 @@ interacts with them:
 
 * Precedence of Traffic Policies: For a given Service, if a traffic policy
   (`externalTrafficPolicy` or `internalTrafficPolicy`) is set to `Local`, it
-  takes precedence over `trafficDistribution: PreferClose` for the corresponding
+  takes precedence over `trafficDistribution` for the corresponding
   traffic type (external or internal, respectively).
 
 * `trafficDistribution` Influence: For a given Service, if a traffic policy
   (`externalTrafficPolicy` or `internalTrafficPolicy`) is set to `Cluster` (the
-  default), or if the fields are not set, then `trafficDistribution:
-  PreferClose` guides the routing behavior for the corresponding traffic type
+  default), or if the fields are not set, then `trafficDistribution`
+  guides the routing behavior for the corresponding traffic type
   (external or internal, respectively). This means that an attempt will be made
   to route traffic to an endpoint that is in the same zone as the client.
 
 ### Considerations for using traffic distribution control  
 
-* **Increased Probability of Overloaded Endpoints:** The `PreferClose`
-  heuristic will attempt to route traffic to the closest healthy endpoints
-  instead of spreading that traffic evenly across all endpoints. If you do not
-  have a sufficient number of endpoints within a zone, they may become
-  overloaded. This is especially likely if incoming traffic is not
-  proportionally distributed across zones. To mitigate this, consider the
-  following strategies:
-
-    * [Pod Topology Spread
-      Constraints](/docs/concepts/scheduling-eviction/topology-spread-constraints/):
-      Use Pod Topology Spread Constraints to distribute your pods more evenly
-      across zones.
-
-    * Zone-specific Deployments: If you expect to see skewed traffic patterns,
-      create a separate Deployment for each zone. This approach allows the
-      separate workloads to scale independently. There are also workload
-      management addons available from the ecosystem, outside the Kubernetes
-      project itself, that can help here.
-
-* **Implementation-specific behavior:** Each dataplane implementation may handle
-  this field slightly differently. If you're using an implementation other than
-  kube-proxy, refer the documentation specific to that implementation to
-  understand how this field is being handled.
+A Service using `trafficDistribution` will attempt to route traffic to (healthy)
+endpoints within the appropriate topology, even if this means that some
+endpoints receive much more traffic than other endpoints. If you do not have a
+sufficient number of endpoints within the same topology ("same zone", "same
+node", etc.) as the clients, then endpoints may become overloaded. This is
+especially likely if incoming traffic is not proportionally distributed across
+the topology. To mitigate this, consider the following strategies:
+
+* [Pod Topology Spread
+  Constraints](/docs/concepts/scheduling-eviction/topology-spread-constraints/):
+  Use Pod Topology Spread Constraints to distribute your pods evenly
+  across zones or nodes.
+
+* Zone-specific Deployments: If you are using "same zone" traffic
+  distribution, but expect to see different traffic patterns in
+  different zones, you can create a separate Deployment for each zone.
+  This approach allows the separate workloads to scale independently.
+  There are also workload management addons available from the
+  ecosystem, outside the Kubernetes project itself, that can help
+  here.
 
 ## {{% heading "whatsnext" %}}