From 02afb71016ac558fc5836738711e78e77b1ad44a Mon Sep 17 00:00:00 2001 From: Swetha Repakula Date: Mon, 15 Mar 2021 11:59:30 -0700 Subject: [PATCH] Update EndpointSlice Docs * Deprecate `endpointslices.discovery.k8s.io/v1beta1` * Removes `content/en/docs/tasks/administer-cluster/enabling-endpointslices.md` and redirects requests to that page to `content/en/docs/concepts/services-networking/endpoint-slices.md` --- .../services-networking/endpoint-slices.md | 45 +++++----- .../concepts/services-networking/service.md | 7 +- .../feature-gates.md | 13 +-- .../reference/labels-annotations-taints.md | 8 ++ .../reference/using-api/deprecation-guide.md | 11 +++ .../enabling-endpointslices.md | 89 ------------------- static/_redirects | 1 + 7 files changed, 54 insertions(+), 120 deletions(-) delete mode 100644 content/en/docs/tasks/administer-cluster/enabling-endpointslices.md diff --git a/content/en/docs/concepts/services-networking/endpoint-slices.md b/content/en/docs/concepts/services-networking/endpoint-slices.md index 6abf1f6ed1..a398e61d07 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. These are 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 on the `endpoint` field of an `EndpointSlice` +resource has been deprecated and is not be supported in the v1 API. Instead, +the v1 API supports setting individual `nodeName` and `zone` fields. These +fields are automatically translated between API versions. For example, the +value of the `"topology.kubernetes.io/zone"` key in the `topology` field in +the v1beta1 API is accessible as 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 b7a7edcd38..2f8a75d515 100644 --- a/content/en/docs/concepts/services-networking/service.md +++ b/content/en/docs/concepts/services-networking/service.md @@ -187,9 +187,14 @@ 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 +If an Endpoints resource has more than 1000 endpoints then a Kubernetes v1.21 (or later) +cluster annotates that Endpoints with `endpoints.kubernetes.io/over-capacity: warning`. +This annotation indicates that the affected Endpoints object 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 2c181ca331..0cd069489d 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 | | @@ -180,7 +176,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 @@ -249,6 +246,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` | GA | 1.21 | - | +| `EndpointSliceNodeName` | `false` | Alpha | 1.20 | 1.21 | +| `EndpointSliceNodeName` | `true` | GA | 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/reference/labels-annotations-taints.md b/content/en/docs/reference/labels-annotations-taints.md index 0399bd561e..08cbf017e6 100644 --- a/content/en/docs/reference/labels-annotations-taints.md +++ b/content/en/docs/reference/labels-annotations-taints.md @@ -221,6 +221,14 @@ Example: `kubectl.kubernetes.io/default-container: "front-end-app"` The value of the annotation is the container name that is default for this Pod. For example, `kubectl logs` or `kubectl exec` without `-c` or `--container` flag will use this default container. +## endpoints.kubernetes.io/over-capacity + +Example: `endpoints.kubernetes.io/over-capacity:warning` + +Used on: Endpoints + +In Kubernetes clusters v1.21 (or later), the Endpoints controller adds this annotation to an Endpoints resource if it has more than 1000 endpoints. The annotation indicates that the Endpoints resource is over capacity. + **The taints listed below are always used on Nodes** ## node.kubernetes.io/not-ready diff --git a/content/en/docs/reference/using-api/deprecation-guide.md b/content/en/docs/reference/using-api/deprecation-guide.md index ee8328cbdd..23c33db16a 100755 --- a/content/en/docs/reference/using-api/deprecation-guide.md +++ b/content/en/docs/reference/using-api/deprecation-guide.md @@ -25,6 +25,17 @@ deprecated API versions to newer and more stable API versions. The **v1.25** release will stop serving the following deprecated API versions: +#### EndpointSlice {#endpointslice-v125} + +The **discovery.k8s.io/v1beta1** API version of EndpointSlice will no longer be served in v1.25. + +* Migrate manifests and API clients to use the **discovery.k8s.io/v1** API version, available since v1.21. +* All existing persisted objects are accessible via the new API +* Notable changes in **discovery.k8s.io/v1**: + * use per Endpoint `nodeName` field instead of deprecated `topology["kubernetes.io/hostname"]` field + * use per Endpoint `zone` field instead of deprecated `topology["topology.kubernetes.io/zone"]` field + * `topology` is replaced with the `deprecatedTopology` field which is not writable in v1 + #### Event {#event-v125} The **events.k8s.io/v1beta1** API version of Event will no longer be served in v1.25. diff --git a/content/en/docs/tasks/administer-cluster/enabling-endpointslices.md b/content/en/docs/tasks/administer-cluster/enabling-endpointslices.md deleted file mode 100644 index d984652de8..0000000000 --- a/content/en/docs/tasks/administer-cluster/enabling-endpointslices.md +++ /dev/null @@ -1,89 +0,0 @@ ---- -reviewers: -- bowei -- freehan -title: Enabling EndpointSlices -content_type: task ---- - - -This page provides an overview of enabling EndpointSlices in Kubernetes. - - - -## {{% heading "prerequisites" %}} - - {{< include "task-tutorial-prereqs.md" >}} {{< version-check >}} - - - - -## Introduction - -EndpointSlices provide a scalable and extensible alternative to Endpoints in -Kubernetes. They build on top of the base of 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. - -## Enabling EndpointSlices - -{{< feature-state for_k8s_version="v1.17" state="beta" >}} - -{{< note >}} -The EndpointSlice resource was designed to address shortcomings in a earlier -resource: Endpoints. Some Kubernetes components and third-party applications -continue to use and rely on Endpoints. Whilst that remains the case, -EndpointSlices should be seen as an addition to Endpoints in a cluster, not as -an outright replacement. -{{< /note >}} - -EndpointSlice functionality in Kubernetes is made up of several different -components, most are enabled by default: -* _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. -* _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. -* _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. -* _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. - - -## 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" %}} - - -* Read about [EndpointSlices](/docs/concepts/services-networking/endpoint-slices/) -* Read [Connecting Applications with Services](/docs/concepts/services-networking/connect-applications-service/) - - diff --git a/static/_redirects b/static/_redirects index 4186c547b2..cd69cddb69 100644 --- a/static/_redirects +++ b/static/_redirects @@ -235,6 +235,7 @@ /docs/tasks/administer-cluster/default-cpu-request-limit/ /docs/tasks/configure-pod-container/assign-cpu-resource/#specify-a-cpu-request-and-a-cpu-limit/ 301 /docs/tasks/administer-cluster/default-memory-request-limit/ /docs/tasks/configure-pod-container/assign-memory-resource/#specify-a-memory-request-and-a-memory-limit/ 301 /docs/tasks/administer-cluster/developing-cloud-controller-manager.md /docs/tasks/administer-cluster/developing-cloud-controller-manager/ 301 +/docs/tasks/administer-cluster/enabling-endpointslices/ /docs/concepts/services-networking/endpoint-slices/ 301 /docs/tasks/administer-cluster/kubeadm/kubeadm-upgrade-1-13 /docs/tasks/administer-cluster/kubeadm/kubeadm-upgrade/ 301 /docs/tasks/administer-cluster/kubeadm/kubeadm-upgrade-ha-1-13 /docs/tasks/administer-cluster/kubeadm/kubeadm-upgrade/ 301 /docs/tasks/administer-cluster/kubeadm/kubeadm-upgrade-1-14 /docs/tasks/administer-cluster/kubeadm/kubeadm-upgrade/ 301