Try to clarify EndpointSlice semantics some more

Especially, the difference between what the API allows, and what the
EndpointSlice controller and kube-proxy support.

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

@@ -25,9 +25,12 @@ import (
 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
 // +k8s:prerelease-lifecycle-gen:introduced=1.21
 
-// EndpointSlice represents a subset of the endpoints that implement a service.
-// For a given service there may be multiple EndpointSlice objects, selected by
-// labels, which must be joined to produce the full set of endpoints.
+// EndpointSlice represents a set of service endpoints. Most EndpointSlices are created by
+// the EndpointSlice controller to represent the Pods selected by Service objects. For a
+// given service there may be multiple EndpointSlice objects which must be joined to
+// produce the full set of endpoints; you can find all of the slices for a given service
+// by listing EndpointSlices in the service's namespace whose `kubernetes.io/service-name`
+// label contains the service's name.
 type EndpointSlice struct {
 	metav1.TypeMeta `json:",inline"`
 
@@ -41,7 +44,10 @@ type EndpointSlice struct {
 	// supported:
 	// * IPv4: Represents an IPv4 Address.
 	// * IPv6: Represents an IPv6 Address.
-	// * FQDN: Represents a Fully Qualified Domain Name.
+	// * FQDN: Represents a Fully Qualified Domain Name. (Deprecated)
+	// The EndpointSlice controller only generates, and kube-proxy only processes,
+	// slices of addressType "IPv4" and "IPv6". No semantics are defined for
+	// the "FQDN" type.
 	AddressType AddressType `json:"addressType" protobuf:"bytes,4,rep,name=addressType"`
 
 	// endpoints is a list of unique endpoints in this slice. Each slice may
@@ -50,10 +56,11 @@ type EndpointSlice struct {
 	Endpoints []Endpoint `json:"endpoints" protobuf:"bytes,2,rep,name=endpoints"`
 
 	// ports specifies the list of network ports exposed by each endpoint in
-	// this slice. Each port must have a unique name. When ports is empty, it
-	// indicates that there are no defined ports. When a port is defined with a
-	// nil port value, it indicates "all ports". Each slice may include a
+	// this slice. Each port must have a unique name. Each slice may include a
 	// maximum of 100 ports.
+	// Services always have at least 1 port, so EndpointSlices generated by the
+	// EndpointSlice controller will likewise always have at least 1 port.
+	// EndpointSlices used for other purposes may have an empty ports list.
 	// +optional
 	// +listType=atomic
 	Ports []EndpointPort `json:"ports" protobuf:"bytes,3,rep,name=ports"`
@@ -76,12 +83,12 @@ const (
 
 // Endpoint represents a single logical "backend" implementing a service.
 type Endpoint struct {
-	// addresses of this endpoint. The contents of this field are interpreted
-	// according to the corresponding EndpointSlice addressType field. Consumers
-	// must handle different types of addresses in the context of their own
-	// capabilities. This must contain at least one address but no more than
-	// 100. These are all assumed to be fungible and clients may choose to only
-	// use the first element. Refer to: https://issue.k8s.io/106267
+	// addresses of this endpoint. For EndpointSlices of addressType "IPv4" or "IPv6",
+	// the values are IP addresses in canonical form. The syntax and semantics of
+	// other addressType values are not defined. This must contain at least one
+	// address but no more than 100. EndpointSlices generated by the EndpointSlice
+	// controller will always have exactly 1 address. No semantics are defined for
+	// additional addresses beyond the first, and kube-proxy does not look at them.
 	// +listType=set
 	Addresses []string `json:"addresses" protobuf:"bytes,1,rep,name=addresses"`
 
@@ -127,26 +134,25 @@ type Endpoint struct {
 
 // EndpointConditions represents the current condition of an endpoint.
 type EndpointConditions struct {
-	// ready indicates that this endpoint is prepared to receive traffic,
+	// ready indicates that this endpoint is ready to receive traffic,
 	// according to whatever system is managing the endpoint. A nil value
-	// indicates an unknown state. In most cases consumers should interpret this
-	// unknown state as ready. For compatibility reasons, ready should never be
-	// "true" for terminating endpoints, except when the normal readiness
-	// behavior is being explicitly overridden, for example when the associated
-	// Service has set the publishNotReadyAddresses flag.
+	// should be interpreted as "true". In general, an endpoint should be
+	// marked ready if it is serving and not terminating, though this can
+	// be overridden in some cases, such as when the associated Service has
+	// set the publishNotReadyAddresses flag.
 	// +optional
 	Ready *bool `json:"ready,omitempty" protobuf:"bytes,1,name=ready"`
 
-	// serving is identical to ready except that it is set regardless of the
-	// terminating state of endpoints. This condition should be set to true for
-	// a ready endpoint that is terminating. If nil, consumers should defer to
-	// the ready condition.
+	// serving indicates that this endpoint is able to receive traffic,
+	// according to whatever system is managing the endpoint. For endpoints
+	// backed by pods, the EndpointSlice controller will mark the endpoint
+	// as serving if the pod's Ready condition is True. A nil value should be
+	// interpreted as "true".
 	// +optional
 	Serving *bool `json:"serving,omitempty" protobuf:"bytes,2,name=serving"`
 
 	// terminating indicates that this endpoint is terminating. A nil value
-	// indicates an unknown state. Consumers should interpret this unknown state
-	// to mean that the endpoint is not terminating.
+	// should be interpreted as "false".
 	// +optional
 	Terminating *bool `json:"terminating,omitempty" protobuf:"bytes,3,name=terminating"`
 }
@@ -183,8 +189,9 @@ type EndpointPort struct {
 	Protocol *v1.Protocol `json:"protocol,omitempty" protobuf:"bytes,2,name=protocol"`
 
 	// port represents the port number of the endpoint.
-	// If this is not specified, ports are not restricted and must be
-	// interpreted in the context of the specific consumer.
+	// If the EndpointSlice is derived from a Kubernetes service, this must be set
+	// to the service's target port. EndpointSlices used for other purposes may have
+	// a nil port.
 	Port *int32 `json:"port,omitempty" protobuf:"bytes,3,opt,name=port"`
 
 	// The application protocol for this port.