Merge pull request #91527 from danwinship/ipfamily-api-docs

api: update Service.Spec.IPFamily docs

api/openapi-spec/swagger.json

@@ -9936,7 +9936,7 @@
           "type": "integer"
         },
         "ipFamily": {
-          "description": "ipFamily specifies whether this Service has a preference for a particular IP family (e.g. IPv4 vs. IPv6).  If a specific IP family is requested, the clusterIP field will be allocated from that family, if it is available in the cluster.  If no IP family is requested, the cluster's primary IP family will be used. Other IP fields (loadBalancerIP, loadBalancerSourceRanges, externalIPs) and controllers which allocate external load-balancers should use the same IP family.  Endpoints for this Service will be of this family.  This field is immutable after creation. Assigning a ServiceIPFamily not available in the cluster (e.g. IPv6 in IPv4 only cluster) is an error condition and will fail during clusterIP assignment.",
+          "description": "ipFamily specifies whether this Service has a preference for a particular IP family (e.g. IPv4 vs. IPv6) when the IPv6DualStack feature gate is enabled. In a dual-stack cluster, you can specify ipFamily when creating a ClusterIP Service to determine whether the controller will allocate an IPv4 or IPv6 IP for it, and you can specify ipFamily when creating a headless Service to determine whether it will have IPv4 or IPv6 Endpoints. In either case, if you do not specify an ipFamily explicitly, it will default to the cluster's primary IP family. This field is part of an alpha feature, and you should not make any assumptions about its semantics other than those described above. In particular, you should not assume that it can (or cannot) be changed after creation time; that it can only have the values \"IPv4\" and \"IPv6\"; or that its current value on a given Service correctly reflects the current state of that Service. (For ClusterIP Services, look at clusterIP to see if the Service is IPv4 or IPv6. For headless Services, look at the endpoints, which may be dual-stack in the future. For ExternalName Services, ipFamily has no meaning, but it may be set to an irrelevant value anyway.)",
           "type": "string"
         },
         "loadBalancerIP": {

pkg/apis/core/types.go

@@ -3524,13 +3524,21 @@ type ServiceSpec struct {
 	// +optional
 	PublishNotReadyAddresses bool
 
-	// ipFamily specifies whether this Service has a preference for a particular IP family (e.g. IPv4 vs.
+	// ipFamily specifies whether this Service has a preference for a particular IP family (e.g.
-	// IPv6).  If a specific IP family is requested, the clusterIP field will be allocated from that family, if it is
+	// IPv4 vs. IPv6) when the IPv6DualStack feature gate is enabled. In a dual-stack cluster,
-	// available in the cluster.  If no IP family is requested, the cluster's primary IP family will be used.
+	// you can specify ipFamily when creating a ClusterIP Service to determine whether the
-	// Other IP fields (loadBalancerIP, loadBalancerSourceRanges, externalIPs) and controllers which
+	// controller will allocate an IPv4 or IPv6 IP for it, and you can specify ipFamily when
-	// allocate external load-balancers should use the same IP family.  Endpoints for this Service will be of
+	// creating a headless Service to determine whether it will have IPv4 or IPv6 Endpoints. In
-	// this family.  This field is immutable after creation. Assigning a ServiceIPFamily not available in the
+	// either case, if you do not specify an ipFamily explicitly, it will default to the
-	// cluster (e.g. IPv6 in IPv4 only cluster) is an error condition and will fail during clusterIP assignment.
+	// cluster's primary IP family.
+	// This field is part of an alpha feature, and you should not make any assumptions about its
+	// semantics other than those described above. In particular, you should not assume that it
+	// can (or cannot) be changed after creation time; that it can only have the values "IPv4"
+	// and "IPv6"; or that its current value on a given Service correctly reflects the current
+	// state of that Service. (For ClusterIP Services, look at clusterIP to see if the Service
+	// is IPv4 or IPv6. For headless Services, look at the endpoints, which may be dual-stack in
+	// the future. For ExternalName Services, ipFamily has no meaning, but it may be set to an
+	// irrelevant value anyway.)
 	// +optional
 	IPFamily *IPFamily
 

staging/src/k8s.io/api/core/v1/generated.proto

@@ -4808,13 +4808,21 @@ message ServiceSpec {
   // +optional
   optional SessionAffinityConfig sessionAffinityConfig = 14;
 
-  // ipFamily specifies whether this Service has a preference for a particular IP family (e.g. IPv4 vs.
+  // ipFamily specifies whether this Service has a preference for a particular IP family (e.g.
-  // IPv6).  If a specific IP family is requested, the clusterIP field will be allocated from that family, if it is
+  // IPv4 vs. IPv6) when the IPv6DualStack feature gate is enabled. In a dual-stack cluster,
-  // available in the cluster.  If no IP family is requested, the cluster's primary IP family will be used.
+  // you can specify ipFamily when creating a ClusterIP Service to determine whether the
-  // Other IP fields (loadBalancerIP, loadBalancerSourceRanges, externalIPs) and controllers which
+  // controller will allocate an IPv4 or IPv6 IP for it, and you can specify ipFamily when
-  // allocate external load-balancers should use the same IP family.  Endpoints for this Service will be of
+  // creating a headless Service to determine whether it will have IPv4 or IPv6 Endpoints. In
-  // this family.  This field is immutable after creation. Assigning a ServiceIPFamily not available in the
+  // either case, if you do not specify an ipFamily explicitly, it will default to the
-  // cluster (e.g. IPv6 in IPv4 only cluster) is an error condition and will fail during clusterIP assignment.
+  // cluster's primary IP family.
+  // This field is part of an alpha feature, and you should not make any assumptions about its
+  // semantics other than those described above. In particular, you should not assume that it
+  // can (or cannot) be changed after creation time; that it can only have the values "IPv4"
+  // and "IPv6"; or that its current value on a given Service correctly reflects the current
+  // state of that Service. (For ClusterIP Services, look at clusterIP to see if the Service
+  // is IPv4 or IPv6. For headless Services, look at the endpoints, which may be dual-stack in
+  // the future. For ExternalName Services, ipFamily has no meaning, but it may be set to an
+  // irrelevant value anyway.)
   // +optional
   optional string ipFamily = 15;
 

staging/src/k8s.io/api/core/v1/types.go

@@ -3993,13 +3993,21 @@ type ServiceSpec struct {
 	// +optional
 	SessionAffinityConfig *SessionAffinityConfig `json:"sessionAffinityConfig,omitempty" protobuf:"bytes,14,opt,name=sessionAffinityConfig"`
 
-	// ipFamily specifies whether this Service has a preference for a particular IP family (e.g. IPv4 vs.
+	// ipFamily specifies whether this Service has a preference for a particular IP family (e.g.
-	// IPv6).  If a specific IP family is requested, the clusterIP field will be allocated from that family, if it is
+	// IPv4 vs. IPv6) when the IPv6DualStack feature gate is enabled. In a dual-stack cluster,
-	// available in the cluster.  If no IP family is requested, the cluster's primary IP family will be used.
+	// you can specify ipFamily when creating a ClusterIP Service to determine whether the
-	// Other IP fields (loadBalancerIP, loadBalancerSourceRanges, externalIPs) and controllers which
+	// controller will allocate an IPv4 or IPv6 IP for it, and you can specify ipFamily when
-	// allocate external load-balancers should use the same IP family.  Endpoints for this Service will be of
+	// creating a headless Service to determine whether it will have IPv4 or IPv6 Endpoints. In
-	// this family.  This field is immutable after creation. Assigning a ServiceIPFamily not available in the
+	// either case, if you do not specify an ipFamily explicitly, it will default to the
-	// cluster (e.g. IPv6 in IPv4 only cluster) is an error condition and will fail during clusterIP assignment.
+	// cluster's primary IP family.
+	// This field is part of an alpha feature, and you should not make any assumptions about its
+	// semantics other than those described above. In particular, you should not assume that it
+	// can (or cannot) be changed after creation time; that it can only have the values "IPv4"
+	// and "IPv6"; or that its current value on a given Service correctly reflects the current
+	// state of that Service. (For ClusterIP Services, look at clusterIP to see if the Service
+	// is IPv4 or IPv6. For headless Services, look at the endpoints, which may be dual-stack in
+	// the future. For ExternalName Services, ipFamily has no meaning, but it may be set to an
+	// irrelevant value anyway.)
 	// +optional
 	IPFamily *IPFamily `json:"ipFamily,omitempty" protobuf:"bytes,15,opt,name=ipFamily,Configcasttype=IPFamily"`
 

staging/src/k8s.io/api/core/v1/types_swagger_doc_generated.go

@@ -2208,7 +2208,7 @@ var map_ServiceSpec = map[string]string{
 	"healthCheckNodePort":      "healthCheckNodePort specifies the healthcheck nodePort for the service. If not specified, HealthCheckNodePort is created by the service api backend with the allocated nodePort. Will use user-specified nodePort value if specified by the client. Only effects when Type is set to LoadBalancer and ExternalTrafficPolicy is set to Local.",
 	"publishNotReadyAddresses": "publishNotReadyAddresses indicates that any agent which deals with endpoints for this Service should disregard any indications of ready/not-ready. The primary use case for setting this field is for a StatefulSet's Headless Service to propagate SRV DNS records for its Pods for the purpose of peer discovery. The Kubernetes controllers that generate Endpoints and EndpointSlice resources for Services interpret this to mean that all endpoints are considered \"ready\" even if the Pods themselves are not. Agents which consume only Kubernetes generated endpoints through the Endpoints or EndpointSlice resources can safely assume this behavior.",
 	"sessionAffinityConfig":    "sessionAffinityConfig contains the configurations of session affinity.",
-	"ipFamily":                 "ipFamily specifies whether this Service has a preference for a particular IP family (e.g. IPv4 vs. IPv6).  If a specific IP family is requested, the clusterIP field will be allocated from that family, if it is available in the cluster.  If no IP family is requested, the cluster's primary IP family will be used. Other IP fields (loadBalancerIP, loadBalancerSourceRanges, externalIPs) and controllers which allocate external load-balancers should use the same IP family.  Endpoints for this Service will be of this family.  This field is immutable after creation. Assigning a ServiceIPFamily not available in the cluster (e.g. IPv6 in IPv4 only cluster) is an error condition and will fail during clusterIP assignment.",
+	"ipFamily":                 "ipFamily specifies whether this Service has a preference for a particular IP family (e.g. IPv4 vs. IPv6) when the IPv6DualStack feature gate is enabled. In a dual-stack cluster, you can specify ipFamily when creating a ClusterIP Service to determine whether the controller will allocate an IPv4 or IPv6 IP for it, and you can specify ipFamily when creating a headless Service to determine whether it will have IPv4 or IPv6 Endpoints. In either case, if you do not specify an ipFamily explicitly, it will default to the cluster's primary IP family. This field is part of an alpha feature, and you should not make any assumptions about its semantics other than those described above. In particular, you should not assume that it can (or cannot) be changed after creation time; that it can only have the values \"IPv4\" and \"IPv6\"; or that its current value on a given Service correctly reflects the current state of that Service. (For ClusterIP Services, look at clusterIP to see if the Service is IPv4 or IPv6. For headless Services, look at the endpoints, which may be dual-stack in the future. For ExternalName Services, ipFamily has no meaning, but it may be set to an irrelevant value anyway.)",
 	"topologyKeys":             "topologyKeys is a preference-order list of topology keys which implementations of services should use to preferentially sort endpoints when accessing this Service, it can not be used at the same time as externalTrafficPolicy=Local. Topology keys must be valid label keys and at most 16 keys may be specified. Endpoints are chosen based on the first topology key with available backends. If this field is specified and all entries have no backends that match the topology of the client, the service has no backends for that client and connections should fail. The special value \"*\" may be used to mean \"any topology\". This catch-all value, if used, only makes sense as the last value in the list. If this is not specified or empty, no topology constraints will be applied.",
 }