Adding initial EndpointSlice documentation

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

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