From a39b576c57a1d3679bc3c39a2df728601e8384e1 Mon Sep 17 00:00:00 2001
From: Rob Scott <robertjscott@google.com>
Date: Thu, 22 Aug 2019 11:40:35 -0700
Subject: [PATCH] Adding initial EndpointSlice documentation

---
 .../services-networking/endpointslice.md      | 97 +++++++++++++++++++
 .../concepts/services-networking/service.md   | 27 ++++++
 2 files changed, 124 insertions(+)
 create mode 100644 content/en/docs/concepts/services-networking/endpointslice.md

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..4974696289286
--- /dev/null
+++ b/content/en/docs/concepts/services-networking/endpointslice.md
@@ -0,0 +1,97 @@
+---
+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 %}}
+
+{{< glossary_definition term_id="endpointslice" length="short" >}}
+
+Endpoint Slices provide a simple way to track network endpoints within a
+Kubernetes cluster. Currently in alpha, they are intended to eventually replace
+the current Endpoints resource 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 like kube-proxy 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. Endpoint Slices are automatically created 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/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
+TODO(robscott)
+
+## Future work
+
+In the future, Endpoint Slices will likely be expanded to support:
+* Additional address types beyond IP.
+* More endpoint condition attributes than ready.
+
+{{% /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 4800af562836a..20c700a675f7a 100644
--- a/content/en/docs/concepts/services-networking/service.md
+++ b/content/en/docs/concepts/services-networking/service.md
@@ -184,6 +184,33 @@ 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 (Alpha)
+Endpoint Slices are a new API resource designed to provide a more scalable
+alternative to Endpoints. Instead of all endpoints for a given service being
+stored in a single Endpoints resource, Endpoint Slices will distribute them
+across multiple resources. 
+
+An equivalent EndpointSlice resource to the Endpoints resource shown above would
+look fairly similar:
+
+```yaml
+apiVersion: discovery/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 the [Endpoint Slice documentation](/docs/concepts/services-networking/endpointslice/).
+
 ## Virtual IPs and service proxies
 
 Every node in a Kubernetes cluster runs a `kube-proxy`. `kube-proxy` is