Topology Aware Hints: Adding SameZone heuristic and other tweaks

keps/sig-network/2433-topology-aware-hints/README.md

@@ -18,9 +18,12 @@
     - [Future API Expansion](#future-api-expansion)
   - [Kube-Proxy](#kube-proxy)
   - [EndpointSlice Controller](#endpointslice-controller)
+  - [Auto Heuristic](#auto-heuristic)
     - [Example](#example)
     - [Overload](#overload)
     - [Handling Node Updates](#handling-node-updates)
+  - [SameZone Heuristic](#samezone-heuristic)
+  - [Additional Heuristics](#additional-heuristics)
   - [Future Expansion](#future-expansion)
   - [Test Plan](#test-plan)
     - [Unit tests](#unit-tests)
@@ -290,7 +293,6 @@ conditions are true:
 
 - Kube-Proxy is able to determine the zone it is running within (likely based
   on node labels).
-- The annotation is set to `Auto`.
 - At least one endpoint for the Service has a hint pointing to the zone
   Kube-Proxy is running within.
 - All endpoints for the Service have zone hints.
@@ -307,9 +309,14 @@ had not yet propagated to all of them.
 ### EndpointSlice Controller
 
 When the `TopologyAwareHints` feature gate is enabled and the annotation is set
-to `Auto` for a Service, the EndpointSlice controller will add hints to
-EndpointSlices. These hints will indicate where an endpoint should be consumed
-by proxy implementations to enable topology aware routing.
+to `Auto` or `SameZone` for a Service, the EndpointSlice controller will add
+hints to EndpointSlices. These hints will indicate where an endpoint should be
+consumed by proxy implementations to enable topology aware routing.
+
+Each heuristic (`Auto` or `SameZone`) will have different logic to determine how
+hints should be allocated. These will be described below:
+
+### Auto Heuristic
 
 The EndpointSlice controller will determine how many endpoints should be
 available for each zone based on the proportion of CPU cores in each zone. If
@@ -369,12 +376,27 @@ of the following scenarios:
 2. A new Node results in a Service that is able to achieve an endpoint
    distribution below 20% for the first time.
 
+### SameZone Heuristic
+The simplest of all heuristics, this will simply copy the zone of an endpoint to
+the hint of the same endpoint. If there are not endpoints available within a zone,
+that will mean no endpoints will have hints for that zone. As described above,
+when Kube-Proxy cannot find any endpoints with hints for its zone, it will route
+traffic ~evenly across all endpoints, regardless of hints.
+
+### Additional Heuristics
+To enable additional heuristics to be added in the future, we will:
+
+1. Remove the requirement in kube-proxy that the hints annotation must be set to
+   a known value on the associated Service before the values of EndpointSlice
+   hints will be considered.
+2. Ensure the EndpointSlice controller TopologyCache provides an interface that
+   simplifies adding additional heuristics in the future.
+
 ### Future Expansion
 
 In the future we may expand this functionality if needed. This could include:
 
-- A new `RequireZone` algorithm that would keep endpoints in EndpointSlices for
-  the same zone they are in.
+- As described above, additional heuristics may be added in the future.
 - A new option to specify a minimum threshold for the `Auto` (PreferZone)
   approach.
 - Support for region based hints.
@@ -467,6 +489,16 @@ EndpointSliceSyncs = metrics.NewCounterVec(
   []string{"result"}, // either "success" or "failure"
 )
 
+// EndpointSliceHints tracks the number of endpoints that have hints assigned.
+EndpointSliceEndpointsWithHints = metrics.NewGaugeVec(
+  &metrics.CounterOpts{
+    Subsystem:      EndpointSliceSubsystem,
+    Name:           "endpoints_with_hints",
+    Help:           "Number of endpoints that have hints assigned",
+    StabilityLevel: metrics.ALPHA,
+  },
+  []string{"result"}, // either "Auto" or "SameZone"
+)
 ```
 
 ### Events

keps/sig-network/2433-topology-aware-hints/kep.yaml

@@ -34,7 +34,7 @@ latest-milestone: "v1.26"
 milestone:
   alpha: "v1.21"
   beta: "v1.23"
-  stable: "v1.26"
+  stable: "v1.27"
 
 # The following PRR answers are required at alpha release
 # List the feature gate name and the components for which it must be enabled