KEP-1645: define dual stack policies and fields

Signed-off-by: Arthur Outhenin-Chalandre <[email protected]>

Author: MrFreezeex

keps/sig-multicluster/1645-multi-cluster-services-api/README.md

@@ -362,10 +362,6 @@ aware routing, but that API is currently in flux. As a result this proposal is
 only suited to same-region multi-cluster services until the topology API
 progresses.
 
-As the plan for dual stack support is finalized, the Multi-Cluster Services API
-will follow dual stack Service design. Until then, dual stack will not be
-supported.
-
 [Service Topology API]:
     https://kubernetes.io/docs/concepts/services-networking/service-topology/
 
@@ -517,6 +513,12 @@ and `spec.exportedAnnotations`. Exporting labels and annotations is optionally
 supported by MCS-API implementations. If supported, annotations or labels must
 not be exported from the `metadata` of the `Service` or `ServiceExport` resources.
 
+An implementation may use the `ipFamilies` field from the exported Services as
+a hint to influence the `IPs` and `ipFamilies` of the ServiceImport object,
+the exact mechanism for determining those field is still implementation defined.
+Also note that even in a dual stack cluster regular Services are by default SingleStack
+([ref](https://kubernetes.io/docs/concepts/services-networking/dual-stack/#dual-stack-options-on-new-services)).
+
 Deleting a `ServiceExport` will stop exporting the name-mapped `Service`.
 
 #### Restricting Exports
@@ -590,10 +592,12 @@ const (
 type ServiceImportSpec struct {
   // +listType=atomic
   Ports []ServicePort `json:"ports"`
-  // +kubebuilder:validation:MaxItems:=1
+  // +kubebuilder:validation:MaxItems:=2
   // +optional
   IPs []string `json:"ips,omitempty"`
   // +optional
+  IPFamilies []corev1.IPFamily `json:"ipFamilies,omitempty"`
+  // +optional
   Type ServiceImportType `json:"type"`
   // +optional
   SessionAffinity corev1.ServiceAffinity `json:"sessionAffinity"`
@@ -655,6 +659,8 @@ metadata:
 spec:
   ips:
   - 42.42.42.42
+  ipFamilies:
+    - IPv4
   type: "ClusterSetIP"
   ports:
   - name: http
@@ -708,12 +714,16 @@ this cluster.
 
 #### ClusterSetIP
 
-A non-headless `ServiceImport` is expected to have an associated IP address, the
-clusterset IP, which may be accessed from within an importing cluster. This IP
-may be a single IP used clusterset-wide or assigned on a per-cluster basis, but
-is expected to be consistent for the life of a `ServiceImport` from the
-perspective of the importing cluster. Requests to this IP from within a cluster
-will route to backends for the aggregated Service.
+A non-headless `ServiceImport` is expected to have associated IP addresses, the
+clusterset IPs, which may be accessed from within an importing cluster. These IPs
+may be used clusterset-wide or assigned on a per-cluster basis, but is expected
+to be consistent for the life of a `ServiceImport` from the perspective of the
+importing cluster. Requests to these IPs from within a cluster will route to
+backends for the aggregated Service. The `IPs` field must correspond to the
+protocol defined in the `ipFamilies` field if defined. How the `ipFamilies`
+field is set is implementation defined, for instance it might correspond to what
+IP protocol the local cluster support or globally reconciled like other
+ServiceImport fields.
 
 Note: this doc does not discuss `NetworkPolicy`, which cannot currently be used
 to describe a selector based policy that applies to a multi-cluster service.