From 0f59654cbd342cce76ba5e4c1661c0ec443efe11 Mon Sep 17 00:00:00 2001 From: Rob Scott Date: Mon, 9 Sep 2019 10:21:18 -0700 Subject: [PATCH] Adding initial EndpointSlice documentation (#16018) --- .../services-networking/endpoint-slices.md | 93 +++++++++++++++++++ .../concepts/services-networking/service.md | 14 +++ .../feature-gates.md | 4 + .../docs/reference/glossary/endpoint-slice.md | 19 ++++ .../enabling-endpoint-slices.md | 55 +++++++++++ data/concepts.yml | 1 + data/tasks.yml | 1 + 7 files changed, 187 insertions(+) create mode 100644 content/en/docs/concepts/services-networking/endpoint-slices.md create mode 100644 content/en/docs/reference/glossary/endpoint-slice.md create mode 100644 content/en/docs/tasks/administer-cluster/enabling-endpoint-slices.md diff --git a/content/en/docs/concepts/services-networking/endpoint-slices.md b/content/en/docs/concepts/services-networking/endpoint-slices.md new file mode 100644 index 0000000000..ec2bfc362b --- /dev/null +++ b/content/en/docs/concepts/services-networking/endpoint-slices.md @@ -0,0 +1,93 @@ +--- +reviewers: +- freehan +title: Endpoint Slices +feature: + title: Endpoint Slices + description: > + Scalable tracking of network endpoints in a Kubernetes cluster. + +content_template: templates/concept +weight: 10 +--- + + +{{% capture overview %}} + +{{< feature-state for_k8s_version="v1.16" state="alpha" >}} +{{< glossary_definition term_id="endpoint-slice" length="short" >}} + +_Endpoint Slices_ provide a simple way to track network endpoints within a +Kubernetes cluster. They offer a more scalable and extensible alternative to +Endpoints. + +{{% /capture %}} + +{{% capture body %}} + +## Endpoint Slice resources {#endpointslice-resource} + +In Kubernetes, an Endpoint Slice contains references to a set of network +endpoints. The EndpointSlice controller automatically creates Endpoint Slices +for a Kubernetes Service when a selector is specified. These Endpoint Slices +will include references to any Pods that match the Service selector. Endpoint +Slices group network endpoints together by unique Service and Port combinations. + +As an example, here's a sample EndpointSlice resource for the `example` +Kubernetes Service. + +```yaml +apiVersion: discovery.k8s.io/v1alpha +kind: EndpointSlice +metadata: + name: example-abc + labels: + kubernetes.io/service-name: example +addressType: IP +ports: + - name: http + protocol: TCP + port: 80 +endpoints: + - addresses: + - "10.1.2.3" + - "2001:db8::1234:5678" + conditions: + ready: true + hostname: pod-1 + topology: + kubernetes.io/hostname: node-1 + topology.kubernetes.io/zone: us-west2-a +``` + +By default, Endpoint Slices managed by the EndpointSlice controller will have no +more than 100 endpoints each. Below this scale, Endpoint Slices should map 1:1 +with Endpoints and Services and have similar performance. + +Endpoint Slices can act as the source of truth for kube-proxy when it comes to +how to route internal traffic. When enabled, they should provide a performance +improvement for services with large numbers of endpoints. + +## Motivation + +The Endpoints API has provided a simple and straightforward way of +tracking network endpoints in Kubernetes. Unfortunately as Kubernetes clusters +and Services have gotten larger, limitations of that API became more visible. +Most notably, those included challenges with scaling to larger numbers of +network endpoints. + +Since all network endpoints for a Service were stored in a single Endpoints +resource, those resources could get quite large. That affected the performance +of Kubernetes components (notably the master control plane) and resulted in +significant amounts of network traffic and processing when Endpoints changed. +Endpoint Slices help you mitigate those issues as well as provide an extensible +platform for additional features such as topological routing. + +{{% /capture %}} + +{{% capture whatsnext %}} + +* [Enabling Endpoint Slices](/docs/tasks/administer-cluster/enabling-endpoint-slices) +* Read [Connecting Applications with Services](/docs/concepts/services-networking/connect-applications-service/) + +{{% /capture %}} diff --git a/content/en/docs/concepts/services-networking/service.md b/content/en/docs/concepts/services-networking/service.md index 6f8c426fa5..2740b4c80e 100644 --- a/content/en/docs/concepts/services-networking/service.md +++ b/content/en/docs/concepts/services-networking/service.md @@ -184,6 +184,19 @@ 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. +### Endpoint Slices +{{< feature-state for_k8s_version="v1.16" state="alpha" >}} + +Endpoint Slices are an API resource that can provide a more scalable alternative +to Endpoints. Although conceptually quite similar to Endpoints, Endpoint Slices +allow for distributing network endpoints across multiple resources. By default, +an Endpoint Slice is considered "full" once it reaches 100 endpoints, at which +point additional Endpoint Slices will be created to store any additional +endpoints. + +Endpoint Slices provide additional attributes and functionality which is +described in detail in [Endpoint Slices](/docs/concepts/services-networking/endpoint-slices/). + ## Virtual IPs and service proxies Every node in a Kubernetes cluster runs a `kube-proxy`. `kube-proxy` is @@ -1148,5 +1161,6 @@ which encompass the current ClusterIP, NodePort, and LoadBalancer modes and more * Read [Connecting Applications with Services](/docs/concepts/services-networking/connect-applications-service/) * Read about [Ingress](/docs/concepts/services-networking/ingress/) +* Read about [Endpoint Slices](/docs/concepts/services-networking/endpoint-slices/) {{% /capture %}} 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 7d9b3dfda1..76be84b769 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 @@ -93,6 +93,7 @@ different Kubernetes components. | `DynamicVolumeProvisioning` | `true` | Alpha | 1.3 | 1.7 | | `DynamicVolumeProvisioning` | `true` | GA | 1.8 | | | `EnableEquivalenceClassCache` | `false` | Alpha | 1.8 | | +| `EndpointSlice` | `false` | Alpha | 1.16 | | | `EphemeralContainers` | `false` | Alpha | 1.16 | | | `ExpandCSIVolumes` | `false` | Alpha | 1.14 | | | `ExpandInUsePersistentVolumes` | `false` | Alpha | 1.11 | 1.14 | @@ -301,6 +302,9 @@ Each feature gate is designed for enabling/disabling a specific feature: host mounts, or containers that are privileged or using specific non-namespaced capabilities (e.g. `MKNODE`, `SYS_MODULE` etc.). This should only be enabled if user namespace remapping is enabled in the Docker daemon. +- `EndpointSlice`: Enables Endpoint Slices for more scalable and extensible + network endpoints. Requires corresponding API and Controller to be enabled. + See [Enabling Endpoint Slices](/docs/tasks/administer-cluster/enabling-endpoint-slices/). - `GCERegionalPersistentDisk`: Enable the regional PD feature on GCE. - `HugePages`: Enable the allocation and consumption of pre-allocated [huge pages](/docs/tasks/manage-hugepages/scheduling-hugepages/). - `HyperVContainer`: Enable [Hyper-V isolation](https://docs.microsoft.com/en-us/virtualization/windowscontainers/manage-containers/hyperv-container) for Windows containers. diff --git a/content/en/docs/reference/glossary/endpoint-slice.md b/content/en/docs/reference/glossary/endpoint-slice.md new file mode 100644 index 0000000000..9715c28fff --- /dev/null +++ b/content/en/docs/reference/glossary/endpoint-slice.md @@ -0,0 +1,19 @@ +--- +title: Endpoint Slice +id: endpoint-slice +date: 2018-04-12 +full_link: /docs/concepts/services-networking/endpoint-slices/ +short_description: > + A way to group network endpoints together with Kubernetes resources. + +aka: +tags: +- networking +--- + A way to group network endpoints together with Kubernetes resources. + + + +A scalable and extensible way to group network endpoints together. These can be +used as by {{< glossary_tooltip text="kube-proxy" term_id="kube-proxy" >}} to +establish network routes on each {{< glossary_tooltip text="node" term_id="node" >}}. diff --git a/content/en/docs/tasks/administer-cluster/enabling-endpoint-slices.md b/content/en/docs/tasks/administer-cluster/enabling-endpoint-slices.md new file mode 100644 index 0000000000..fb137b4778 --- /dev/null +++ b/content/en/docs/tasks/administer-cluster/enabling-endpoint-slices.md @@ -0,0 +1,55 @@ +--- +reviewers: +- bowei +- freehan +title: Enabling Endpoint Slices +content_template: templates/task +--- + +{{% capture overview %}} +This page provides an overview of enabling Endpoint Slices in Kubernetes. +{{% /capture %}} + + +{{% capture prerequisites %}} + {{< include "task-tutorial-prereqs.md" >}} {{< version-check >}} +{{% /capture %}} + +{{% capture steps %}} + +## Introduction + +Endpoint Slices 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 Endpoint Slice +resources instead of a single large Endpoints resource. + +## Enabling Endpoint Slices +As an alpha feature, Endpoint Slices are not enabled by default in Kubernetes. +Enabling Endpoint Slices requires as many as 3 changes to Kubernetes cluster +configuration. + +To enable the Discovery API group that includes Endpoint Slices, use the runtime + config flag (`--runtime-config=discovery.k8s.io/v1alpha1=true`). + +The logic responsible for watching services, pods, and nodes and creating or +updating associated Endpoint Slices lives within the EndpointSlice controller. +This is disabled by default but can be enabled with the controllers flag on +kube-controller-manager (`--controllers=endpointslice`). + +For Kubernetes components like kube-proxy to actually start using Endpoint +Slices, the EndpointSlice feature gate will need to be enabled +(`--feature-gates=EndpointSlice=true`). + +## Using Endpoint Slices + +With Endpoint Slices fully enabled in your cluster, you should see corresponding +EndpointSlice resources for each Endpoints resource. In addition to supporting +existing Endpoints functionality, Endpoint Slices should include new bits of +information such as topology. They will allow for greater scalability and +extensibility of network endpoints in your cluster. + +### Feature availability + +Kubernetes 1.16 or newer is required to use Endpoint Slices. diff --git a/data/concepts.yml b/data/concepts.yml index 1141aac6d0..998b265e06 100644 --- a/data/concepts.yml +++ b/data/concepts.yml @@ -93,6 +93,7 @@ toc: - docs/concepts/services-networking/dns-pod-service.md - docs/concepts/services-networking/connect-applications-service.md - docs/concepts/services-networking/ingress.md + - docs/concepts/services-networking/endpoint-slices.md - docs/concepts/services-networking/network-policies.md - docs/concepts/services-networking/add-entries-to-pod-etc-hosts-with-host-aliases.md - docs/concepts/services-networking/dual-stack.md diff --git a/data/tasks.yml b/data/tasks.yml index 6b854effc2..5159c2282f 100644 --- a/data/tasks.yml +++ b/data/tasks.yml @@ -194,6 +194,7 @@ toc: - docs/tasks/administer-cluster/dns-debugging-resolution.md - docs/tasks/administer-cluster/pvc-protection.md - docs/tasks/administer-cluster/storage-object-in-use-protection.md + - docs/tasks/administer-cluster/endpoint-slices.md - title: Federation - Run an App on Multiple Clusters landing_page: /docs/tasks/federation/set-up-cluster-federation-kubefed/