From 9b3a4bb411a1134395370f1ba54daa734f043b6c Mon Sep 17 00:00:00 2001 From: Dan Winship Date: Sat, 23 May 2020 12:44:41 -0400 Subject: [PATCH] api: update Service.Spec.IPFamily docs --- api/openapi-spec/swagger.json | 2 +- pkg/apis/core/types.go | 22 +++++++++++++------ .../src/k8s.io/api/core/v1/generated.proto | 22 +++++++++++++------ staging/src/k8s.io/api/core/v1/types.go | 22 +++++++++++++------ .../core/v1/types_swagger_doc_generated.go | 2 +- 5 files changed, 47 insertions(+), 23 deletions(-) diff --git a/api/openapi-spec/swagger.json b/api/openapi-spec/swagger.json index 4417cc9eef4..3672d87ec1d 100644 --- a/api/openapi-spec/swagger.json +++ b/api/openapi-spec/swagger.json @@ -9915,7 +9915,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": { diff --git a/pkg/apis/core/types.go b/pkg/apis/core/types.go index 4ec44c0db10..0e1403c7ccc 100644 --- a/pkg/apis/core/types.go +++ b/pkg/apis/core/types.go @@ -3517,13 +3517,21 @@ type ServiceSpec struct { // +optional PublishNotReadyAddresses bool - // 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 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.) // +optional IPFamily *IPFamily diff --git a/staging/src/k8s.io/api/core/v1/generated.proto b/staging/src/k8s.io/api/core/v1/generated.proto index 9babe37bb61..555d9a38fa3 100644 --- a/staging/src/k8s.io/api/core/v1/generated.proto +++ b/staging/src/k8s.io/api/core/v1/generated.proto @@ -4799,13 +4799,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. - // 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 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.) // +optional optional string ipFamily = 15; diff --git a/staging/src/k8s.io/api/core/v1/types.go b/staging/src/k8s.io/api/core/v1/types.go index 197684de76c..7c21c162fa2 100644 --- a/staging/src/k8s.io/api/core/v1/types.go +++ b/staging/src/k8s.io/api/core/v1/types.go @@ -3985,13 +3985,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. - // 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 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.) // +optional IPFamily *IPFamily `json:"ipFamily,omitempty" protobuf:"bytes,15,opt,name=ipFamily,Configcasttype=IPFamily"` diff --git a/staging/src/k8s.io/api/core/v1/types_swagger_doc_generated.go b/staging/src/k8s.io/api/core/v1/types_swagger_doc_generated.go index 13325261274..136d8c44abf 100644 --- a/staging/src/k8s.io/api/core/v1/types_swagger_doc_generated.go +++ b/staging/src/k8s.io/api/core/v1/types_swagger_doc_generated.go @@ -2207,7 +2207,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, when set to true, indicates that DNS implementations must publish the notReadyAddresses of subsets for the Endpoints associated with the Service. The default value is false. The primary use case for setting this field is to use a StatefulSet's Headless Service to propagate SRV records for its Pods without respect to their readiness for purpose of peer discovery.", "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.", }