diff --git a/content/en/docs/concepts/services-networking/endpointslice.md b/content/en/docs/concepts/services-networking/endpointslice.md new file mode 100644 index 0000000000000..d8cea1165c083 --- /dev/null +++ b/content/en/docs/concepts/services-networking/endpointslice.md @@ -0,0 +1,108 @@ +--- +reviewers: +- freehan +title: Endpoint Slice +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="endpointslice" length="short" >}} + +_Endpoint Slices_ provide a simple way to track network endpoints within a +Kubernetes cluster. They offer a more scalable alternative to Endpoints +resources within Kubernetes. + +{{% /capture %}} + +{{% capture body %}} + +## Motivation + +The current 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 when Endpoints changed. With kube-proxy +running on each node, each Endpoints change resulted in the full resource being +transmitted to each node. In some cases, Endpoints resources became large enough +to hit the upper limit on the size of a single object in etcd. + +Endpoint Slices were designed to mitigate those issues as well as provide an +extensible platform for additional features such as topological routing. + +## 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 with a selector 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. By +default, Endpoint Slices will have no more than 100 endpoints each. + +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 +``` + +## 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`). + +## What's Next + +{{% /capture %}} + +{{% capture whatsnext %}} + +* 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 6f8c426fa5405..601730ab685d2 100644 --- a/content/en/docs/concepts/services-networking/service.md +++ b/content/en/docs/concepts/services-networking/service.md @@ -184,6 +184,38 @@ 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 a new API resource designed to 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. + +An equivalent EndpointSlice resource to the Endpoints resource shown above would +look fairly similar: + +```yaml +apiVersion: discovery.k8s.io/v1alpha1 +kind: EndpointSlice +metadata: + name: my-service-abcd +subsets: + - endpoints: + - addresses: + - "192.0.2.42" + conditions: + ready: true + ports: + - port: 9376 + protocol: TCP +``` + +Endpoint Slices provide additional attributes and functionality which is +described in detail in [Endpoint Slices](/docs/concepts/services-networking/endpointslice/). + ## Virtual IPs and service proxies Every node in a Kubernetes cluster runs a `kube-proxy`. `kube-proxy` is