Service topology alpha documentation

content/en/docs/concepts/services-networking/service-topology.md

@@ -0,0 +1,127 @@
+---
+reviewers:
+- johnbelamaric
+- imroc
+title: Service Topology
+feature:
+  title: Service Topology
+  description: >
+    Routing of service traffice based upon cluster topology.
+
+content_template: templates/concept
+weight: 10
+---
+
+
+{{% capture overview %}}
+
+{{< feature-state for_k8s_version="v1.17" state="alpha" >}}
+
+_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.
+
+{{% /capture %}}
+
+{{% capture body %}}
+
+## Introduction
+
+By default, traffic sent to a `ClusterIP` or `NodePort` Service may be routed to
+any backend address for the Service. Since Kubernetes 1.7 it has been possible
+to route "external" traffic to the Pods running on the Node that received the
+traffic, but this is not supported for `ClusterIP` Services, and more complex
+topologies &mdash; such as routing zonally &mdash; have not been possible. The
+_Service Topology_ feature resolves this by allowing the Service creator to
+define a policy for routing traffic based upon the Node labels for the
+originating and destination Nodes.
+
+By using Node label matching between the source and destination, the operator
+may designate groups of Nodes that are "closer" and "farther" from one another,
+using whatever metric makes sense for that operator's requirements. For many
+operators in public clouds, for example, there is a preference to keep service
+traffic withing the same zone, because interzonal traffic has a cost associated
+with it, while intrazonal traffic does not. Other common needs include being able
+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
+
+If your cluster has Service Topology enabled, you can control Service traffic
+routing by specifying the `topologyKeys` field on the Service spec. This field
+is a preference-order list of Node labels which will be used to sort endpoints
+when accessing this Service. Traffic will be directed to a Node whose value for
+the first label matches the originating Node's value for that label. If there is
+no backend for the Service on a matching Node, then the second label will be
+considered, and so forth, until no labels remain.
+
+If no match is found, the traffic will be rejected, just as if there were no
+backends for the Service at all. That is, endpoints are chosen based on the first
+topology key with available backends. If this field is specified and all entries
+have no backends that match the topology of the client, the service has no
+backends for that client and connections should fail. The special value `"*"` may
+be used to mean "any topology". This catch-all value, if used, only makes sense
+as the last value in the list.
+
+If `topologyKeys` is not specified or empty, no topology constraints will be applied.
+
+Consider a cluster with Nodes that are labeled with their hostname, zone name,
+and region name. Then you can set the `topologyKeys` values of a service to direct
+traffic as follows.
+
+* Only to endpoints on the same node, failing if no endpoint exists on the node:
+  `["kubernetes.io/hostname"]`.
+* Preferentially to endpoints on the same node, falling back to endpoints in the
+  same zone, followed by the same region, and failing otherwise: `["kubernetes.io/hostname",
+  "topology.kubernetes.io/zone", "topology.kubernetes.io/region"]`.
+  This may be useful, for example, in cases where data locality is critical.
+* Preferentially to the same zone, but fallback on any available endpoint if
+  none are available within this zone:
+  `["topology.kubernetes.io/zone", "*"]`.
+
+
+
+## Constraints
+
+* Service topology is not compatible with `externalTrafficPolicy=Local`, and
+  therefore a Service cannot use both of these features. It is possible to use
+  both features in the same cluster on different Services, just not on the same
+  Service.
+
+* Valid topology keys are currently limited to `kubernetes.io/hostname`,
+  `topology.kubernetes.io/zone`, and `topology.kubernetes.io/region`, but will
+  be generalized to other node labels in the future.
+
+* Topology keys must be valid label keys and at most 16 keys may be specified.
+
+* The catch-all value, `"*"`, must be the last value in the topology keys, if
+  it is used.
+
+
+{{% /capture %}}
+
+{{% capture whatsnext %}}
+
+* Read about [enabling Service Topology](/docs/tasks/administer-cluster/enabling-service-topology)
+* Read [Connecting Applications with Services](/docs/concepts/services-networking/connect-applications-service/)
+
+{{% /capture %}}