From 461c486e1e1a09cbb2a56685a7288948c89f6b33 Mon Sep 17 00:00:00 2001 From: John Belamaric Date: Wed, 6 Nov 2019 11:09:15 -0800 Subject: [PATCH] Service topology alpha documentation --- .../services-networking/service-topology.md | 127 ++++++++++++++++++ 1 file changed, 127 insertions(+) create mode 100644 content/en/docs/concepts/services-networking/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 new file mode 100644 index 0000000000000..39df51e862868 --- /dev/null +++ b/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 — such as routing zonally — 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 %}}