Update EndpointSlice Docs

content/en/docs/concepts/services-networking/endpoint-slices.md

@@ -9,7 +9,7 @@ weight: 35
 
 <!-- overview -->
 
-{{< feature-state for_k8s_version="v1.17" state="beta" >}}
+{{< feature-state for_k8s_version="v1.21" state="stable" >}}
 
 _EndpointSlices_ provide a simple way to track network endpoints within a
 Kubernetes cluster. They offer a more scalable and extensible alternative to
@@ -52,7 +52,7 @@ As an example, here's a sample EndpointSlice resource for the `example`
 Kubernetes Service.
 
 ```yaml
-apiVersion: discovery.k8s.io/v1beta1
+apiVersion: discovery.k8s.io/v1
 kind: EndpointSlice
 metadata:
  name: example-abc
@@ -69,9 +69,8 @@ endpoints:
  conditions:
  ready: true
  hostname: pod-1
- topology:
- kubernetes.io/hostname: node-1
- topology.kubernetes.io/zone: us-west2-a
+ nodeName: node-1
+ zone: us-west2-a
 ```
 
 By default, the control plane creates and manages EndpointSlices to have no
@@ -135,29 +134,41 @@ For pods, this is any pod that has a deletion timestamp set.
 
 ### Topology information {#topology}
 
-{{< feature-state for_k8s_version="v1.20" state="deprecated" >}}
-
-{{< note >}}
-The topology field in EndpointSlices has been deprecated and will be removed in
-a future release. A new `nodeName` field will be used instead of setting
-`kubernetes.io/hostname` in topology. It was determined that other topology
-fields covering zone and region would be better represented as EndpointSlice
-labels that would apply to all endpoints within the EndpointSlice.
-{{< /note >}}
-
 Each endpoint within an EndpointSlice can contain relevant topology information.
 This is used to indicate where an endpoint is, containing information about the
-corresponding Node, zone, and region. When the values are available, the
-control plane sets the following Topology labels for EndpointSlices:
+corresponding Node, zone. When the values are available, the
+control plane sets the following per endpoint fields for EndpointSlices:
 
-* `kubernetes.io/hostname` - The name of the Node this endpoint is on.
-* `topology.kubernetes.io/zone` - The zone this endpoint is in.
-* `topology.kubernetes.io/region` - The region this endpoint is in.
+* `nodeName` - The name of the Node this endpoint is on.
+* `zone` - The zone this endpoint is in.
 
-The values of these labels are derived from resources associated with each
-endpoint in a slice. The hostname label represents the value of the NodeName
-field on the corresponding Pod. The zone and region labels represent the value
-of the labels with the same names on the corresponding Node.
+#### Deprecated per endpoint `topology` field
+In the GA API, the field `deprecatedTopology` was added for backwards
+compatibility with the `topology` field that exists on the v1beta1 API. The
+`topology` will be converted to `depcreatedTopology` and will be available as
+a read only field for `v1` clients. Any attempts by a `v1` client to write to
+`deprecatedTopology` will cause the entire field to dropped. The
+`deprecatedTopology` will be removed when the `v1beta1` API is removed.
+
+{{< note >}}
+During conversion from `v1beta1` to `v1`, the following special cases exist:
+* If the `topology.kubernetes.io/zone` key is present, it will not be added to
+ the `deprecatedTopology` field and instead will be available on the per
+ endpoint `zone field`.
+* If the `kubernetes.io/hostname` key is present and it matches the value of
+ the per endpoint `nodeName` field the key will not be added to the
+ `deprecatedTopology` field. If the values do not match, the key will
+ continue to exist in `deprecatedTopology`.
+
+During conversion from `v1` to `v1beta1`, the following special cases exist:
+* The per endpoint `zone` field will be added into the per endpoint `topology`
+ field with the key `topology.kubernetes.io/zone`.
+* If the per endpoint `nodeName` field exists and the `kubernetes.io/hostname`
+ key does not exist in the per endpoint `topology` map, the `nodeName` value
+ will be added to the map with the key `kubernetes.io/hostname`. If the key
+ is present, then the value will be unchanged. The per endpoint `nodeName`
+ value will stay the same will not be affected by the conversion.
+{{< /note >}}
 
 ### Management
 

content/en/docs/concepts/services-networking/service.md

@@ -187,6 +187,13 @@ An ExternalName Service is a special case of Service that does not have
 selectors and uses DNS names instead. For more information, see the
 [ExternalName](#externalname) section later in this document.
 
+### Over Capacity Endpoints
+Starting in Kubernetes 1.21, if an Endpoints resource has more than a 1000
+endpoints the controlplane will add an annotation
+`endpoints.kubernetes.io/over-capacity: warning` and value `warning` to indicate
+that the Endpoints resource is over capacity. In future releases, addressess
+will will be truncated after the first 1000.
+
 ### EndpointSlices
 
 {{< feature-state for_k8s_version="v1.17" state="beta" >}}

content/en/docs/reference/command-line-tools-reference/feature-gates.md

@@ -103,10 +103,6 @@ different Kubernetes components.
 | `DynamicKubeletConfig` | `false` | Alpha | 1.4 | 1.10 |
 | `DynamicKubeletConfig` | `true` | Beta | 1.11 | |
 | `EfficientWatchResumption` | `false` | Alpha | 1.20 | |
-| `EndpointSlice` | `false` | Alpha | 1.16 | 1.16 |
-| `EndpointSlice` | `false` | Beta | 1.17 | |
-| `EndpointSlice` | `true` | Beta | 1.18 | |
-| `EndpointSliceNodeName` | `false` | Alpha | 1.20 | |
 | `EndpointSliceProxying` | `false` | Alpha | 1.18 | 1.18 |
 | `EndpointSliceProxying` | `true` | Beta | 1.19 | |
 | `EndpointSliceTerminatingCondition` | `false` | Alpha | 1.20 | |
@@ -245,6 +241,12 @@ different Kubernetes components.
 | `EnableAggregatedDiscoveryTimeout` | `true` | Deprecated | 1.16 | - |
 | `EnableEquivalenceClassCache` | `false` | Alpha | 1.8 | 1.14 |
 | `EnableEquivalenceClassCache` | - | Deprecated | 1.15 | - |
+| `EndpointSlice` | `false` | Alpha | 1.16 | 1.16 |
+| `EndpointSlice` | `false` | Beta | 1.17 | |
+| `EndpointSlice` | `true` | Beta | 1.18 | |
+| `EndpointSlice` | `true` | Stable | 1.21 | |
+| `EndpointSliceNodeName` | `false` | Alpha | 1.20 | |
+| `EndpointSliceNodeName` | `true` | Stable | 1.21 | |
 | `ExperimentalCriticalPodAnnotation` | `false` | Alpha | 1.5 | 1.12 |
 | `ExperimentalCriticalPodAnnotation` | `false` | Deprecated | 1.13 | - |
 | `EvenPodsSpread` | `false` | Alpha | 1.16 | 1.17 |
@@ -580,7 +582,9 @@ Each feature gate is designed for enabling/disabling a specific feature:
  nodes when scheduling Pods.
 - `EndpointSlice`: Enables EndpointSlices for more scalable and extensible
  network endpoints. See [Enabling EndpointSlices](/docs/tasks/administer-cluster/enabling-endpointslices/).
-- `EndpointSliceNodeName`: Enables EndpointSlice `nodeName` field.
+ This feature has graduated and cannot be disabled.
+- `EndpointSliceNodeName`: Enables EndpointSlice `nodeName` field. This
+ feature has graduated and cannot be disabled.
 - `EndpointSliceProxying`: When enabled, kube-proxy running
  on Linux will use EndpointSlices as the primary data source instead of
  Endpoints, enabling scalability and performance improvements. See

content/en/docs/tasks/administer-cluster/enabling-endpointslices.md

@@ -28,7 +28,7 @@ resources instead of a single large Endpoints resource.
 
 ## Enabling EndpointSlices
 
-{{< feature-state for_k8s_version="v1.17" state="beta" >}}
+{{< feature-state for_k8s_version="v1.21" state="stable" >}}
 
 {{< note >}}
 The EndpointSlice resource was designed to address shortcomings in a earlier
@@ -39,19 +39,16 @@ an outright replacement.
 {{< /note >}}
 
 EndpointSlice functionality in Kubernetes is made up of several different
-components, most are enabled by default:
+components:
 * _The EndpointSlice API_: EndpointSlices are part of the
- `discovery.k8s.io/v1beta1` API. This is beta and enabled by default since
- Kubernetes 1.17. All components listed below are dependent on this API being
- enabled.
+ `discovery.k8s.io/v1` API. This is stable starting from Kubernetes 1.21.
+ All components listed below are dependent on this API.
 * _The EndpointSlice Controller_: This {{< glossary_tooltip text="controller"
  term_id="controller" >}} maintains EndpointSlices for Services and the Pods
- they reference. This is controlled by the `EndpointSlice` feature gate. It has
- been enabled by default since Kubernetes 1.18.
+ they reference.
 * _The EndpointSliceMirroring Controller_: This {{< glossary_tooltip
  text="controller" term_id="controller" >}} mirrors custom Endpoints to
- EndpointSlices. This is controlled by the `EndpointSlice` feature gate. It has
- been enabled by default since Kubernetes 1.19.
+ EndpointSlices.
 * _Kube-Proxy_: When {{< glossary_tooltip text="kube-proxy" term_id="kube-proxy">}}
  is configured to use EndpointSlices, it can support higher numbers of Service
  endpoints. This is controlled by the `EndpointSliceProxying` feature gate on
@@ -67,8 +64,6 @@ components, most are enabled by default:
 
 Some fields in the EndpointSlice API are feature-gated.
 
-- The `EndpointSliceNodeName` feature gate controls access to the `nodeName`
- field. This is an alpha feature that is disabled by default.
 - The `EndpointSliceTerminating` feature gate controls access to the `serving`
  and `terminating` condition fields. This is an alpha feature that is disabled
  by default.