11---
22reviewers :
33- robscott
4- title : Topology Aware Hints
4+ title : Topology Aware Routing
55content_type : concept
66weight : 100
77description : >-
8- _Topology Aware Hints_ provides a mechanism to help keep network traffic within the zone
8+ _Topology Aware Routing_ provides a mechanism to help keep network traffic within the zone
99 where it originated. Preferring same-zone traffic between Pods in your cluster can help
1010 with reliability, performance (network latency and throughput), or cost.
1111---
@@ -15,45 +15,68 @@ description: >-
1515
1616{{< feature-state for_k8s_version="v1.23" state="beta" >}}
1717
18- _ Topology Aware Hints_ enable topology aware routing by including suggestions
19- for how clients should consume endpoints. This approach adds metadata to enable
20- consumers of EndpointSlice (or Endpoints) objects, so that traffic to
21- those network endpoints can be routed closer to where it originated.
18+ {{< note >}}
19+ Prior to Kubernetes 1.27, this feature was known as _ Topology Aware Hints_ .
20+ {{</ note >}}
2221
23- For example, you can route traffic within a locality to reduce
24- costs, or to improve network performance.
22+ _ Topology Aware Routing_ adjusts routing behavior to prefer keeping traffic in
23+ the zone it originated from. In some cases this can help reduce costs or improve
24+ network performance.
2525
2626<!-- body -->
2727
2828## Motivation
2929
3030Kubernetes clusters are increasingly deployed in multi-zone environments.
31- _ Topology Aware Hints _ provides a mechanism to help keep traffic within the zone
32- it originated from. This concept is commonly referred to as "Topology Aware
33- Routing". When calculating the endpoints for a {{< glossary_tooltip term_id="Service" >}},
34- the EndpointSlice controller considers the topology (region and zone) of each endpoint
35- and populates the hints field to allocate it to a zone.
36- Cluster components such as the {{< glossary_tooltip term_id="kube-proxy" text="kube-proxy" >}}
37- can then consume those hints, and use them to influence how the traffic is routed
38- (favoring topologically closer endpoints).
31+ _ Topology Aware Routing _ provides a mechanism to help keep traffic within the
32+ zone it originated from. When calculating the endpoints for a {{<
33+ glossary_tooltip term_id="Service" >}}, the EndpointSlice controller considers
34+ the topology (region and zone) of each endpoint and populates the hints field to
35+ allocate it to a zone. Cluster components such as {{< glossary_tooltip
36+ term_id="kube-proxy" text="kube-proxy" >}} can then consume those hints, and use
37+ them to influence how the traffic is routed (favoring topologically closer
38+ endpoints).
3939
40- ## Using Topology Aware Hints
40+ ## Enabling Topology Aware Routing
4141
42- You can activate Topology Aware Hints for a Service by setting the
43- ` service.kubernetes.io/topology-aware-hints ` annotation to ` auto ` . This tells
44- the EndpointSlice controller to set topology hints if it is deemed safe .
45- Importantly, this does not guarantee that hints will always be set.
42+ {{< note >}}
43+ Prior to Kubernetes 1.27, this behavior was controlled using the
44+ ` service.kubernetes.io/ topology-aware- hints` annotation .
45+ {{</ note >}}
4646
47- ## How it works {#implementation}
47+ You can enable Topology Aware Routing for a Service by setting the
48+ ` service.kubernetes.io/topology-mode ` annotation to ` Auto ` . When there are
49+ enough endpoints available in each zone, Topology Hints will be populated on
50+ EndpointSlices to allocate individual endpoints to specific zones, resulting in
51+ traffic being routed closer to where it originated from.
4852
49- The functionality enabling this feature is split into two components: The
50- EndpointSlice controller and the kube-proxy. This section provides a high level overview
51- of how each component implements this feature.
53+ ## When it works best
54+
55+ This feature works best when:
56+
57+ ### 1. Incoming traffic is evenly distributed
58+
59+ If a large proportion of traffic is originating from a single zone, that traffic
60+ could overload the subset of endpoints that have been allocated to that zone.
61+ This feature is not recommended when incoming traffic is expected to originate
62+ from a single zone.
63+
64+ ### 2. The Service has 3 or more endpoints per zone {#three-or-more-endpoints-per-zone}
65+ In a three zone cluster, this means 9 or more endpoints. If there are fewer than
66+ 3 endpoints per zone, there is a high (≈50%) probability that the EndpointSlice
67+ controller will not be able to allocate endpoints evenly and instead will fall
68+ back to the default cluster-wide routing approach.
69+
70+ ## How It Works
71+
72+ The "Auto" heuristic attempts to proportionally allocate a number of endpoints
73+ to each zone. Note that this heuristic works best for Services that have a
74+ significant number of endpoints.
5275
5376### EndpointSlice controller {#implementation-control-plane}
5477
5578The EndpointSlice controller is responsible for setting hints on EndpointSlices
56- when this feature is enabled. The controller allocates a proportional amount of
79+ when this heuristic is enabled. The controller allocates a proportional amount of
5780endpoints to each zone. This proportion is based on the
5881[ allocatable] ( /docs/tasks/administer-cluster/reserve-compute-resources/#node-allocatable )
5982CPU cores for nodes running in that zone. For example, if one zone had 2 CPU
@@ -145,6 +168,11 @@ zone.
145168 proportions of each zone. This could have unintended consequences if a large
146169 portion of nodes are unready.
147170
171+ * The EndpointSlice controller ignores nodes with the
172+ ` node-role.kubernetes.io/control-plane` or `node-role.kubernetes.io/master`
173+ label set. This could be problematic if workloads are also running on those
174+ nodes.
175+
148176* The EndpointSlice controller does not take into account {{< glossary_tooltip
149177 text="tolerations" term_id="toleration" >}} when deploying or calculating the
150178 proportions of each zone. If the Pods backing a Service are limited to a
@@ -157,6 +185,17 @@ zone.
157185 either not picking up on this event, or newly added pods starting in a
158186 different zone.
159187
188+
189+ # # Custom heuristics
190+
191+ Kubernetes is deployed in many different ways, there is no single heuristic for
192+ allocating endpoints to zones will work for every use case. A key goal of this
193+ feature is to enable custom heuristics to be developed if the built in heuristic
194+ does not work for your use case. The first steps to enable custom heuristics
195+ were included in the 1.27 release. This is a limited implementation that may not
196+ yet cover some relevant and plausible situations.
197+
198+
160199# # {{% heading "whatsnext" %}}
161200
162201* Follow the [Connecting Applications with Services](/docs/tutorials/services/connect-applications-service/) tutorial
0 commit comments