Merge pull request #45276 from gauravkghildiyal/new-topology-field

Document .spec.trafficDistribution field in Service

Author: k8s-ci-robot

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

@@ -967,6 +967,35 @@ to control how Kubernetes routes traffic to healthy (“ready”) backends.
 
 See [Traffic Policies](/docs/reference/networking/virtual-ips/#traffic-policies) for more details.
 
+### Trafic distribution
+
+{{< feature-state feature_gate_name="ServiceTrafficDistribution" >}}
+
+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
+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.
+
+If the field is not set, the implementation will apply its default routing strategy.
+
+See [Traffic
+Distribution](/docs/reference/networking/virtual-ips/#traffic-distribution) for
+more details
+
 ### Session stickiness
 
 If you want to make sure that connections from a particular client are passed to

content/en/docs/concepts/services-networking/topology-aware-routing.md

@@ -198,3 +198,8 @@ yet cover some relevant and plausible situations.
 ## {{% heading "whatsnext" %}}
 
 * Follow the [Connecting Applications with Services](/docs/tutorials/services/connect-applications-service/) tutorial
+* Learn about the
+  [trafficDistribution](/docs/concepts/services-networking/service/#trafic-distribution)
+  field, which is closely related to the `service.kubernetes.io/topology-mode`
+  annotation and provides flexible options for traffic routing within
+  Kubernetes.

content/en/docs/reference/command-line-tools-reference/feature-gates/service-traffic-distribution.md

@@ -0,0 +1,16 @@
+---
+title: ServiceTrafficDistribution
+content_type: feature_gate
+
+_build:
+  list: never
+  render: false
+
+stages:
+- stage: alpha 
+  defaultValue: false
+  fromVersion: "1.30"
+---
+Allows usage of the optional `spec.trafficDistribution` field in Services. The
+field offers a way to express preferences for how traffic is distributed to
+Service endpoints.

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

@@ -513,6 +513,94 @@ those terminating Pods. By the time the Pod completes termination, the external
 should have seen the node's health check failing and fully removed the node from the backend
 pool.
 
+## Traffic Distribution
+
+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.
+
+### 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:
+
+* `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
+  overload](#considerations-for-using-traffic-distribution-control).
+
+If the `service.kubernetes.io/topology-mode` annotation is set to `Auto`, it
+will take precedence over `trafficDistribution`. (The annotation may be deprecated
+in the future in favour of the `trafficDistribution` field).
+
+### Interaction with Traffic Policies
+
+When compared to the `trafficDistribution` field, the traffic policy fields
+(`externalTrafficPolicy` and `internalTrafficPolicy`) are meant to offer a
+stricter traffic locality requirements. Here's how `trafficDistribution`
+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
+  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
+  (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.
+
 ## {{% heading "whatsnext" %}}
 
 To learn more about Services,