Merge pull request kubernetes#130673 from gauravkghildiyal/kep-4444-ga

Promote ServiceTrafficDistribution feature-gate to GA and update docs with latest descriptions

Author: k8s-ci-robot

api/openapi-spec/swagger.json

@@ -4548,13 +4548,11 @@ const (
 
 // These are valid values for the TrafficDistribution field of a Service.
 const (
-	// 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. 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.
 	ServiceTrafficDistributionPreferClose = "PreferClose"
 )
 
@@ -4822,12 +4820,12 @@ type ServiceSpec struct {
 	// +optional
 	InternalTrafficPolicy *ServiceInternalTrafficPolicy
 
-	// TrafficDistribution offers a way to express preferences for how traffic is
-	// distributed to Service endpoints. Implementations can use this field as a
-	// hint, but are not required to guarantee strict adherence. If the field is
-	// not set, the implementation will apply its default routing strategy. If set
-	// to "PreferClose", implementations should prioritize endpoints that are
-	// topologically close (e.g., same zone).
+	// TrafficDistribution offers a way to express preferences for how traffic
+	// is distributed to Service endpoints. Implementations can use this field
+	// as a hint, but are not required to guarantee strict adherence. If the
+	// field is not set, the implementation will apply its default routing
+	// strategy. If set to "PreferClose", implementations should prioritize
+	// endpoints that are in the same zone.
 	// +optional
 	TrafficDistribution *string
 }

api/openapi-spec/v3/api__v1_openapi.json

@@ -713,6 +713,7 @@ var defaultVersionedKubernetesFeatureGates = map[featuregate.Feature]featuregate
 	ServiceTrafficDistribution: {
 		{Version: version.MustParse("1.30"), Default: false, PreRelease: featuregate.Alpha},
 		{Version: version.MustParse("1.31"), Default: true, PreRelease: featuregate.Beta},
+		{Version: version.MustParse("1.33"), Default: true, PreRelease: featuregate.GA, LockToDefault: true}, // GA and LockToDefault in 1.33, remove in 1.36
 	},
 
 	SidecarContainers: {

pkg/apis/core/types.go

@@ -18,9 +18,7 @@ package proxy
 
 import (
 	v1 "k8s.io/api/core/v1"
-	utilfeature "k8s.io/apiserver/pkg/util/feature"
 	"k8s.io/klog/v2"
-	"k8s.io/kubernetes/pkg/features"
 )
 
 // CategorizeEndpoints returns:
@@ -41,7 +39,7 @@ func CategorizeEndpoints(endpoints []Endpoint, svcInfo ServicePort, nodeLabels m
 	var useTopology, useServingTerminatingEndpoints bool
 
 	if svcInfo.UsesClusterEndpoints() {
-		useTopology = canUseTopology(endpoints, svcInfo, nodeLabels)
+		useTopology = canUseTopology(endpoints, nodeLabels)
 		clusterEndpoints = filterEndpoints(endpoints, func(ep Endpoint) bool {
 			if !ep.IsReady() {
 				return false
@@ -137,29 +135,11 @@ func CategorizeEndpoints(endpoints []Endpoint, svcInfo ServicePort, nodeLabels m
 	return
 }
 
-// canUseTopology returns true if topology aware routing is enabled and properly
-// configured in this cluster. That is, it checks that:
-//   - The TopologyAwareHints or ServiceTrafficDistribution feature is enabled.
-//   - If ServiceTrafficDistribution feature gate is not enabled, then the
-//     hintsAnnotation should represent an enabled value.
+// canUseTopology returns true if all of the following is true:
 //   - The node's labels include "topology.kubernetes.io/zone".
 //   - All of the endpoints for this Service have a topology hint.
 //   - At least one endpoint for this Service is hinted for this node's zone.
-func canUseTopology(endpoints []Endpoint, svcInfo ServicePort, nodeLabels map[string]string) bool {
-	if !utilfeature.DefaultFeatureGate.Enabled(features.TopologyAwareHints) && !utilfeature.DefaultFeatureGate.Enabled(features.ServiceTrafficDistribution) {
-		return false
-	}
-
-	// Ignore value of hintsAnnotation if the ServiceTrafficDistribution feature
-	// gate is enabled.
-	if !utilfeature.DefaultFeatureGate.Enabled(features.ServiceTrafficDistribution) {
-		// If the hintsAnnotation has a disabled value, we do not consider hints for route programming.
-		hintsAnnotation := svcInfo.HintsAnnotation()
-		if hintsAnnotation == "" || hintsAnnotation == "disabled" || hintsAnnotation == "Disabled" {
-			return false
-		}
-	}
-
+func canUseTopology(endpoints []Endpoint, nodeLabels map[string]string) bool {
 	zone, foundZone := nodeLabels[v1.LabelTopologyZone]
 	hasEndpointForZone := false
 	for _, endpoint := range endpoints {

pkg/features/versioned_kube_features.go

@@ -47,13 +47,12 @@ func checkExpectedEndpoints(expected sets.Set[string], actual []Endpoint) error
 
 func TestCategorizeEndpoints(t *testing.T) {
 	testCases := []struct {
-		name                      string
-		hintsEnabled              bool
-		trafficDistFeatureEnabled bool
-		pteEnabled                bool
-		nodeLabels                map[string]string
-		serviceInfo               ServicePort
-		endpoints                 []Endpoint
+		name         string
+		hintsEnabled bool
+		pteEnabled   bool
+		nodeLabels   map[string]string
+		serviceInfo  ServicePort
+		endpoints    []Endpoint
 
 		// We distinguish `nil` ("service doesn't use this kind of endpoints") from
 		// `sets.Set[string]()` ("service uses this kind of endpoints but has no endpoints").
@@ -79,7 +78,7 @@ func TestCategorizeEndpoints(t *testing.T) {
 		clusterEndpoints: sets.New[string]("10.1.2.3:80", "10.1.2.6:80"),
 		localEndpoints:   nil,
 	}, {
-		name:         "hints, hints annotation == disabled, hints ignored",
+		name:         "hints, hints annotation == disabled, but endpointslice hints are not ignored since trafficDist feature-gate is always enabled by default",
 		hintsEnabled: true,
 		nodeLabels:   map[string]string{v1.LabelTopologyZone: "zone-a"},
 		serviceInfo:  &BaseServicePortInfo{hintsAnnotation: "disabled"},
@@ -89,20 +88,7 @@ func TestCategorizeEndpoints(t *testing.T) {
 			&BaseEndpointInfo{endpoint: "10.1.2.5:80", zoneHints: sets.New[string]("zone-c"), ready: true},
 			&BaseEndpointInfo{endpoint: "10.1.2.6:80", zoneHints: sets.New[string]("zone-a"), ready: true},
 		},
-		clusterEndpoints: sets.New[string]("10.1.2.3:80", "10.1.2.4:80", "10.1.2.5:80", "10.1.2.6:80"),
-		localEndpoints:   nil,
-	}, {
-		name:         "hints disabled, hints annotation == auto",
-		hintsEnabled: false,
-		nodeLabels:   map[string]string{v1.LabelTopologyZone: "zone-a"},
-		serviceInfo:  &BaseServicePortInfo{hintsAnnotation: "auto"},
-		endpoints: []Endpoint{
-			&BaseEndpointInfo{endpoint: "10.1.2.3:80", zoneHints: sets.New[string]("zone-a"), ready: true},
-			&BaseEndpointInfo{endpoint: "10.1.2.4:80", zoneHints: sets.New[string]("zone-b"), ready: true},
-			&BaseEndpointInfo{endpoint: "10.1.2.5:80", zoneHints: sets.New[string]("zone-c"), ready: true},
-			&BaseEndpointInfo{endpoint: "10.1.2.6:80", zoneHints: sets.New[string]("zone-a"), ready: true},
-		},
-		clusterEndpoints: sets.New[string]("10.1.2.3:80", "10.1.2.4:80", "10.1.2.5:80", "10.1.2.6:80"),
+		clusterEndpoints: sets.New[string]("10.1.2.3:80", "10.1.2.6:80"),
 		localEndpoints:   nil,
 	}, {
 
@@ -119,24 +105,10 @@ func TestCategorizeEndpoints(t *testing.T) {
 		clusterEndpoints: sets.New[string]("10.1.2.3:80", "10.1.2.6:80"),
 		localEndpoints:   nil,
 	}, {
-		name:         "hints, hints annotation empty, hints ignored",
+		name:         "hints, hints annotation empty but endpointslice hints are not ignored since trafficDist feature-gate is always enabled by default",
 		hintsEnabled: true,
 		nodeLabels:   map[string]string{v1.LabelTopologyZone: "zone-a"},
-		serviceInfo:  &BaseServicePortInfo{},
-		endpoints: []Endpoint{
-			&BaseEndpointInfo{endpoint: "10.1.2.3:80", zoneHints: sets.New[string]("zone-a"), ready: true},
-			&BaseEndpointInfo{endpoint: "10.1.2.4:80", zoneHints: sets.New[string]("zone-b"), ready: true},
-			&BaseEndpointInfo{endpoint: "10.1.2.5:80", zoneHints: sets.New[string]("zone-c"), ready: true},
-			&BaseEndpointInfo{endpoint: "10.1.2.6:80", zoneHints: sets.New[string]("zone-a"), ready: true},
-		},
-		clusterEndpoints: sets.New[string]("10.1.2.3:80", "10.1.2.4:80", "10.1.2.5:80", "10.1.2.6:80"),
-		localEndpoints:   nil,
-	}, {
-		name:                      "hints, hints annotation empty but trafficDist feature gate enabled, hints are not ignored",
-		hintsEnabled:              true,
-		trafficDistFeatureEnabled: true,
-		nodeLabels:                map[string]string{v1.LabelTopologyZone: "zone-a"},
-		serviceInfo:               &BaseServicePortInfo{},
+		serviceInfo:  &BaseServicePortInfo{ /* hints annotation empty */ },
 		endpoints: []Endpoint{
 			&BaseEndpointInfo{endpoint: "10.1.2.3:80", zoneHints: sets.New[string]("zone-a"), ready: true},
 			&BaseEndpointInfo{endpoint: "10.1.2.4:80", zoneHints: sets.New[string]("zone-b"), ready: true},
@@ -146,11 +118,10 @@ func TestCategorizeEndpoints(t *testing.T) {
 		clusterEndpoints: sets.New[string]("10.1.2.3:80", "10.1.2.6:80"),
 		localEndpoints:   nil,
 	}, {
-		name:                      "hints disabled, trafficDist feature gate enabled, hints are not ignored",
-		hintsEnabled:              false,
-		trafficDistFeatureEnabled: true,
-		nodeLabels:                map[string]string{v1.LabelTopologyZone: "zone-a"},
-		serviceInfo:               &BaseServicePortInfo{},
+		name:         "hints feature-gate disabled but endpointslice hints are not ignored since trafficDist feature-gate is always enabled by default",
+		hintsEnabled: false,
+		nodeLabels:   map[string]string{v1.LabelTopologyZone: "zone-a"},
+		serviceInfo:  &BaseServicePortInfo{},
 		endpoints: []Endpoint{
 			&BaseEndpointInfo{endpoint: "10.1.2.3:80", zoneHints: sets.New[string]("zone-a"), ready: true},
 			&BaseEndpointInfo{endpoint: "10.1.2.4:80", zoneHints: sets.New[string]("zone-b"), ready: true},
@@ -160,11 +131,10 @@ func TestCategorizeEndpoints(t *testing.T) {
 		clusterEndpoints: sets.New[string]("10.1.2.3:80", "10.1.2.6:80"),
 		localEndpoints:   nil,
 	}, {
-		name:                      "externalTrafficPolicy: Local, topology ignored for Local endpoints",
-		hintsEnabled:              true,
-		trafficDistFeatureEnabled: true,
-		nodeLabels:                map[string]string{v1.LabelTopologyZone: "zone-a"},
-		serviceInfo:               &BaseServicePortInfo{externalPolicyLocal: true, nodePort: 8080, hintsAnnotation: "auto"},
+		name:         "externalTrafficPolicy: Local, topology ignored for Local endpoints",
+		hintsEnabled: true,
+		nodeLabels:   map[string]string{v1.LabelTopologyZone: "zone-a"},
+		serviceInfo:  &BaseServicePortInfo{externalPolicyLocal: true, nodePort: 8080, hintsAnnotation: "auto"},
 		endpoints: []Endpoint{
 			&BaseEndpointInfo{endpoint: "10.1.2.3:80", zoneHints: sets.New[string]("zone-a"), ready: true, isLocal: true},
 			&BaseEndpointInfo{endpoint: "10.1.2.4:80", zoneHints: sets.New[string]("zone-b"), ready: true, isLocal: true},
@@ -175,11 +145,10 @@ func TestCategorizeEndpoints(t *testing.T) {
 		localEndpoints:   sets.New[string]("10.1.2.3:80", "10.1.2.4:80"),
 		allEndpoints:     sets.New[string]("10.1.2.3:80", "10.1.2.4:80", "10.1.2.6:80"),
 	}, {
-		name:                      "internalTrafficPolicy: Local, topology ignored for Local endpoints",
-		hintsEnabled:              true,
-		trafficDistFeatureEnabled: true,
-		nodeLabels:                map[string]string{v1.LabelTopologyZone: "zone-a"},
-		serviceInfo:               &BaseServicePortInfo{internalPolicyLocal: true, hintsAnnotation: "auto", externalPolicyLocal: false, nodePort: 8080},
+		name:         "internalTrafficPolicy: Local, topology ignored for Local endpoints",
+		hintsEnabled: true,
+		nodeLabels:   map[string]string{v1.LabelTopologyZone: "zone-a"},
+		serviceInfo:  &BaseServicePortInfo{internalPolicyLocal: true, hintsAnnotation: "auto", externalPolicyLocal: false, nodePort: 8080},
 		endpoints: []Endpoint{
 			&BaseEndpointInfo{endpoint: "10.1.2.3:80", zoneHints: sets.New[string]("zone-a"), ready: true, isLocal: true},
 			&BaseEndpointInfo{endpoint: "10.1.2.4:80", zoneHints: sets.New[string]("zone-b"), ready: true, isLocal: true},
@@ -271,32 +240,6 @@ func TestCategorizeEndpoints(t *testing.T) {
 		},
 		clusterEndpoints: sets.New[string]("10.1.2.3:80", "10.1.2.6:80"),
 		localEndpoints:   nil,
-	}, {
-		name:         "hintsAnnotation empty, no filtering applied",
-		hintsEnabled: true,
-		nodeLabels:   map[string]string{v1.LabelTopologyZone: "zone-a"},
-		serviceInfo:  &BaseServicePortInfo{hintsAnnotation: ""},
-		endpoints: []Endpoint{
-			&BaseEndpointInfo{endpoint: "10.1.2.3:80", zoneHints: sets.New[string]("zone-a"), ready: true},
-			&BaseEndpointInfo{endpoint: "10.1.2.4:80", zoneHints: sets.New[string]("zone-b"), ready: true},
-			&BaseEndpointInfo{endpoint: "10.1.2.5:80", zoneHints: sets.New[string]("zone-c"), ready: true},
-			&BaseEndpointInfo{endpoint: "10.1.2.6:80", zoneHints: sets.New[string]("zone-a"), ready: true},
-		},
-		clusterEndpoints: sets.New[string]("10.1.2.3:80", "10.1.2.4:80", "10.1.2.5:80", "10.1.2.6:80"),
-		localEndpoints:   nil,
-	}, {
-		name:         "hintsAnnotation disabled, no filtering applied",
-		hintsEnabled: true,
-		nodeLabels:   map[string]string{v1.LabelTopologyZone: "zone-a"},
-		serviceInfo:  &BaseServicePortInfo{hintsAnnotation: "disabled"},
-		endpoints: []Endpoint{
-			&BaseEndpointInfo{endpoint: "10.1.2.3:80", zoneHints: sets.New[string]("zone-a"), ready: true},
-			&BaseEndpointInfo{endpoint: "10.1.2.4:80", zoneHints: sets.New[string]("zone-b"), ready: true},
-			&BaseEndpointInfo{endpoint: "10.1.2.5:80", zoneHints: sets.New[string]("zone-c"), ready: true},
-			&BaseEndpointInfo{endpoint: "10.1.2.6:80", zoneHints: sets.New[string]("zone-a"), ready: true},
-		},
-		clusterEndpoints: sets.New[string]("10.1.2.3:80", "10.1.2.4:80", "10.1.2.5:80", "10.1.2.6:80"),
-		localEndpoints:   nil,
 	}, {
 		name:         "missing hints, no filtering applied",
 		hintsEnabled: true,
@@ -489,7 +432,6 @@ func TestCategorizeEndpoints(t *testing.T) {
 	for _, tc := range testCases {
 		t.Run(tc.name, func(t *testing.T) {
 			featuregatetesting.SetFeatureGateDuringTest(t, utilfeature.DefaultFeatureGate, features.TopologyAwareHints, tc.hintsEnabled)
-			featuregatetesting.SetFeatureGateDuringTest(t, utilfeature.DefaultFeatureGate, features.ServiceTrafficDistribution, tc.trafficDistFeatureEnabled)
 
 			clusterEndpoints, localEndpoints, allEndpoints, hasAnyEndpoints := CategorizeEndpoints(tc.endpoints, tc.serviceInfo, tc.nodeLabels)