From bc0cda724f7c34b4e873e0b7f39ec07a88cd4cd4 Mon Sep 17 00:00:00 2001 From: Swetha Repakula Date: Mon, 15 Mar 2021 11:59:30 -0700 Subject: [PATCH] Update EndpointSlice Docs --- .../services-networking/endpoint-slices.md | 45 ++++++++---------- .../concepts/services-networking/service.md | 8 +++- .../feature-gates.md | 13 ++++-- .../enabling-endpointslices.md | 46 ++++++++----------- 4 files changed, 55 insertions(+), 57 deletions(-) diff --git a/content/en/docs/concepts/services-networking/endpoint-slices.md b/content/en/docs/concepts/services-networking/endpoint-slices.md index 6abf1f6ed12e2..3ca4d58aa3032 100644 --- a/content/en/docs/concepts/services-networking/endpoint-slices.md +++ b/content/en/docs/concepts/services-networking/endpoint-slices.md @@ -9,7 +9,7 @@ weight: 35 -{{< 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,30 +134,26 @@ For pods, this is any pod that has a deletion timestamp set. ### Topology information {#topology} -{{< feature-state for_k8s_version="v1.20" state="deprecated" >}} +Each endpoint within an EndpointSlice can contain relevant topology information. +The topology information includes the location of the endpoint and information +about the corresponding Node and zone. This will be available in the following +per endpoint fields on EndpointSlices: + +* `nodeName` - The name of the Node this endpoint is on. +* `zone` - The zone this endpoint is in. {{< 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. +In the v1 API, the per endpoint `topology` was effectively removed in favor of +the dedicated fields `nodeName` and `zone`. + +Setting arbitrary topology fields per endpoint has been deprecated and will not +be supported in the v1 API. Instead, the v1 API supports setting individual +node name and zone fields. These fields will be automatically translated +between API versions. For example, the value of +topology[topology.kubernetes.io/zone] in the v1beta1 API will be accessible in +the zone field in the v1 API. {{< /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: - -* `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. - -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. - ### Management Most often, the control plane (specifically, the endpoint slice diff --git a/content/en/docs/concepts/services-networking/service.md b/content/en/docs/concepts/services-networking/service.md index b7a7edcd386a9..84381e0770a6e 100644 --- a/content/en/docs/concepts/services-networking/service.md +++ b/content/en/docs/concepts/services-networking/service.md @@ -187,9 +187,15 @@ 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 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. + ### EndpointSlices -{{< feature-state for_k8s_version="v1.17" state="beta" >}} +{{< feature-state for_k8s_version="v1.21" state="stable" >}} EndpointSlices are an API resource that can provide a more scalable alternative to Endpoints. Although conceptually quite similar to Endpoints, EndpointSlices diff --git a/content/en/docs/reference/command-line-tools-reference/feature-gates.md b/content/en/docs/reference/command-line-tools-reference/feature-gates.md index 5500c19412460..bf4072d7b9d47 100644 --- a/content/en/docs/reference/command-line-tools-reference/feature-gates.md +++ b/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 | | @@ -179,7 +175,8 @@ different Kubernetes components. | `WinDSR` | `false` | Alpha | 1.14 | | | `WinOverlay` | `false` | Alpha | 1.14 | 1.19 | | `WinOverlay` | `true` | Beta | 1.20 | | -| `WindowsEndpointSliceProxying` | `false` | Alpha | 1.19 | | +| `WindowsEndpointSliceProxying` | `false` | Alpha | 1.19 | 1.20 | +| `WindowsEndpointSliceProxying` | `true` | beta | 1.21 | | {{< /table >}} ### Feature gates for graduated or deprecated features @@ -245,6 +242,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 | 1.17 | +| `EndpointSlice` | `true` | Beta | 1.18 | 1.21 | +| `EndpointSlice` | `true` | Stable | 1.21 | - | +| `EndpointSliceNodeName` | `false` | Alpha | 1.20 | 1.21 | +| `EndpointSliceNodeName` | `true` | Stable | 1.21 | - | | `ExperimentalCriticalPodAnnotation` | `false` | Alpha | 1.5 | 1.12 | | `ExperimentalCriticalPodAnnotation` | `false` | Deprecated | 1.13 | - | | `EvenPodsSpread` | `false` | Alpha | 1.16 | 1.17 | diff --git a/content/en/docs/tasks/administer-cluster/enabling-endpointslices.md b/content/en/docs/tasks/administer-cluster/enabling-endpointslices.md index d984652de8ec0..8801eeb977ae6 100644 --- a/content/en/docs/tasks/administer-cluster/enabling-endpointslices.md +++ b/content/en/docs/tasks/administer-cluster/enabling-endpointslices.md @@ -21,14 +21,22 @@ This page provides an overview of enabling EndpointSlices in Kubernetes. ## Introduction EndpointSlices provide a scalable and extensible alternative to Endpoints in -Kubernetes. They build on top of the base of functionality provided by Endpoints +Kubernetes. They build on top of the base functionality provided by Endpoints and extend that in a scalable way. When Services have a large number (>100) of network endpoints, they will be split into multiple smaller EndpointSlice -resources instead of a single large Endpoints resource. +resources instead of a single large Endpoints resource. EndpointSlices allow +for greater scalability and extensibility of network endpoints in your +cluster. + +{{< note >}} +Though the Endpoints API has not been deprecated, it should be considered as +the legacy API. The EndpointSlice API should be preferred over the Endpoint +API. +{{< /note >}} ## 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,47 +47,33 @@ 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 - Linux and `WindowsEndpointSliceProxying` on Windows. It has been enabled by - default on Linux since Kubernetes 1.19. It is not enabled by default for - Windows nodes. To configure kube-proxy to use EndpointSlices on Windows, you - can enable the `WindowsEndpointSliceProxying` [feature - gate](/docs/reference/command-line-tools-reference/feature-gates/) on - kube-proxy. + Linux and `WindowsEndpointSliceProxying` [feature + gate](/docs/reference/command-line-tools-reference/feature-gates/) on Windows. + It has been enabled by default on Linux since Kubernetes 1.19, and on Windows + since Kubernetes 1.21. ## API fields 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. -## Using EndpointSlices - -With EndpointSlices fully enabled in your cluster, you should see corresponding -EndpointSlice resources for each Endpoints resource. In addition to supporting -existing Endpoints functionality, EndpointSlices will allow for greater -scalability and extensibility of network endpoints in your cluster. - ## {{% heading "whatsnext" %}}