Adding initial EndpointSlice documentation (#16018)

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 %}}

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 %}}

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.

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.
+
+<!--more-->
+
+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" >}}.

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.

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

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/