From 79e1b94c91bcfa3740b1dbcbaa072971527215fc Mon Sep 17 00:00:00 2001
From: Andrew Sy Kim <kiman@vmware.com>
Date: Thu, 6 Feb 2020 16:11:26 -0500
Subject: [PATCH] Add common examples to Service Topology documentation
 (#18712)

* service topology: add missing 'enabling service topology' page

Signed-off-by: Andrew Sy Kim <kiman@vmware.com>

* service topology: add common examples

Signed-off-by: Andrew Sy Kim <kiman@vmware.com>
---
 .../services-networking/service-topology.md   | 109 +++++++++++++++---
 .../enabling-service-topology.md              |  54 +++++++++
 2 files changed, 146 insertions(+), 17 deletions(-)
 create mode 100644 content/en/docs/tasks/administer-cluster/enabling-service-topology.md

diff --git a/content/en/docs/concepts/services-networking/service-topology.md b/content/en/docs/concepts/services-networking/service-topology.md
index 223cf86c3e..7b3c58a84a 100644
--- a/content/en/docs/concepts/services-networking/service-topology.md
+++ b/content/en/docs/concepts/services-networking/service-topology.md
@@ -46,23 +46,6 @@ with it, while intrazonal traffic does not. Other common needs include being abl
 to route traffic to a local Pod managed by a DaemonSet, or keeping traffic to
 Nodes connected to the same top-of-rack switch for the lowest latency.
 
-## Prerequisites
-
-The following prerequisites are needed in order to enable topology aware service
-routing:
-
-   * Kubernetes 1.17 or later
-   * Kube-proxy running in iptables mode or IPVS mode
-   * Enable [Endpoint Slices](/docs/concepts/services-networking/endpoint-slices/)
-
-## Enable Service Topology
-
-To enable service topology, enable the `ServiceTopology` feature gate for
-kube-apiserver and kube-proxy:
-
-```
---feature-gates="ServiceTopology=true"
-```
 
 ## Using Service Topology
 
@@ -117,6 +100,98 @@ traffic as follows.
   it is used.
 
 
+## Examples
+
+The following are common examples of using the Service Topology feature.
+
+### Only Node Local Endpoints
+
+A Service that only routes to node local endpoints. If no endpoints exist on the node, traffic is dropped:
+
+```yaml
+apiVersion: v1
+kind: Service
+metadata:
+  name: my-service
+spec:
+  selector:
+    app: my-app
+  ports:
+    - protocol: TCP
+      port: 80
+      targetPort: 9376
+  topologyKeys:
+    - "kubernetes.io/hostname"
+```
+
+### Prefer Node Local Endpoints
+
+A Service that prefers node local Endpoints but falls back to cluster wide endpoints if node local endpoints do not exist:
+
+```yaml
+apiVersion: v1
+kind: Service
+metadata:
+  name: my-service
+spec:
+  selector:
+    app: my-app
+  ports:
+    - protocol: TCP
+      port: 80
+      targetPort: 9376
+  topologyKeys:
+    - "kubernetes.io/hostname"
+    - "*"
+```
+
+
+### Only Zonal or Regional Endpoints
+
+A Service that prefers zonal then regional endpoints. If no endpoints exist in either, traffic is dropped.
+
+
+```yaml
+apiVersion: v1
+kind: Service
+metadata:
+  name: my-service
+spec:
+  selector:
+    app: my-app
+  ports:
+    - protocol: TCP
+      port: 80
+      targetPort: 9376
+  topologyKeys:
+    - "topology.kubernetes.io/zone"
+    - "topology.kubernetes.io/region"
+```
+
+### Prefer Node Local, Zonal, then Regional Endpoints
+
+A Service that prefers node local, zonal, then regional endpoints but falls back to cluster wide endpoints.
+
+```yaml
+apiVersion: v1
+kind: Service
+metadata:
+  name: my-service
+spec:
+  selector:
+    app: my-app
+  ports:
+    - protocol: TCP
+      port: 80
+      targetPort: 9376
+  topologyKeys:
+    - "kubernetes.io/hostname"
+    - "topology.kubernetes.io/zone"
+    - "topology.kubernetes.io/region"
+    - "*"
+```
+
+
 {{% /capture %}}
 
 {{% capture whatsnext %}}
diff --git a/content/en/docs/tasks/administer-cluster/enabling-service-topology.md b/content/en/docs/tasks/administer-cluster/enabling-service-topology.md
new file mode 100644
index 0000000000..c39b9b366d
--- /dev/null
+++ b/content/en/docs/tasks/administer-cluster/enabling-service-topology.md
@@ -0,0 +1,54 @@
+---
+reviewers:
+- andrewsykim
+- johnbelamaric
+- imroc
+title: Enabling Service Topology
+content_template: templates/task
+---
+
+{{% capture overview %}}
+This page provides an overview of enabling Service Topology in Kubernetes.
+{{% /capture %}}
+
+
+{{% capture prerequisites %}}
+  {{< include "task-tutorial-prereqs.md" >}} {{< version-check >}}
+{{% /capture %}}
+
+{{% capture steps %}}
+
+## Introduction
+
+_Service Topology_ enables a service to route traffic based upon the Node
+topology of the cluster. For example, a service can specify that traffic be
+preferentially routed to endpoints that are on the same Node as the client, or
+in the same availability zone.
+
+## Prerequisites
+
+The following prerequisites are needed in order to enable topology aware service
+routing:
+
+   * Kubernetes 1.17 or later
+   * {{< glossary_tooltip text="Kube-proxy" term_id="kube-proxy" >}} running in iptables mode or IPVS mode
+   * Enable [Endpoint Slices](/docs/concepts/services-networking/endpoint-slices/)
+
+## Enable Service Topology
+
+{{< feature-state for_k8s_version="v1.17" state="alpha" >}}
+
+To enable service topology, enable the `ServiceTopology` and `EndpointSlice` feature gate for all Kubernetes components:
+
+```
+--feature-gates="ServiceTopology=true,EndpointSlice=true"
+```
+
+
+{{% capture whatsnext %}}
+
+* Read about the [Service Topology](/docs/concepts/services-networking/service-topology) concept
+* Read about [Endpoint Slices](/docs/concepts/services-networking/endpoint-slices)
+* Read [Connecting Applications with Services](/docs/concepts/services-networking/connect-applications-service/)
+
+{{% /capture %}}