Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Adding feature documentation and task instructions for topology aware hints #1579

Open
wants to merge 5 commits into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 21 additions & 0 deletions linkerd.io/content/2.12/features/topology-aware-hints.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
+++
title = "Topology Aware Hints"
description = "Linkerd's implementation of Kubernetes topology aware hints enables endpoint consumption based on a node's zone label."
aliases = [
"../topology-aware-hints/"
]
+++

Kuberentes clusters are increasingly deployed in multi-zone environments with network traffic often relying on obscured endpoint matching and routing for a given service. Linkerd's implementation of Kubernetes ([Topology Aware Hints][topology aware hints]) provides users with a mechanism for asserting more control over endpoint selection and routing within a distributed cluster. Users can now implement routing constraints and prefer endpoints in a specific zone in order to limit cross-zone networking costs or improve performance through lowered cross-zone latency and bandwidth constraints.
deusxanima marked this conversation as resolved.
Show resolved Hide resolved

The goal of topology aware hints is to to provide a simpler way for users to prefer endpoints by basing decisions soely off the node's `topology.kubernetes.io/zone` label. If a node is in zone-a, then it should prefer endpoints that should be consumed by clients in zone-a. When the feature is enabled and the label set, Linkerd's destination controller will serve endpoints that match the endpoint's `Hints.ForZones` field with the zone value that matches that of the requesting client.
deusxanima marked this conversation as resolved.
Show resolved Hide resolved

{{< note >}}

Topology aware hints require Linkerd `endpointSlice` feature to be turned on (enabled by default starting with Linkerd stable-2.12.x) along with the `TopologyAwareHints` feature gate which MUST be enabled in the Kubernetes cluster.
deusxanima marked this conversation as resolved.
Show resolved Hide resolved

{{< /note >}}

To get started with topology aware hints take a look at the [enabling topology aware hints](../tasks/enabling-topology-aware-hints/) task documentation.

[topology aware hints]: https://kubernetes.io/docs/concepts/services-networking/topology-aware-hints/
39 changes: 39 additions & 0 deletions linkerd.io/content/2.12/tasks/enabling-topology-aware-hints.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
+++
title = "Enabling Topology Aware Hints"
description = "Enable topology aware hints to allow Linkerd to intelligently choose same-zone endpoints"
+++

[Topology aware hints](../features/topology-aware-hints/) allow Linkerd users to specify endpoint selection boundaries when a request is made against a service, making it possible to limit cross-zone endpoint selection and lower the associated costs and latency.

There are three requirements to successfully enabling topology aware hints with Linkerd:

1. Topology Aware Hints feature gate MUST be enabled on the Kubernetes cluster.
deusxanima marked this conversation as resolved.
Show resolved Hide resolved
2. Each Kubernetes node should be labeled with the `"topology.kubernetes.io/zone` label.
3. Relevant Kuberentes services will need to be modified with the `service.kubernetes.io/topology-aware-hints=auto` annotation.
deusxanima marked this conversation as resolved.
Show resolved Hide resolved

When Linkerd receives a set of endpoint slices and translates them to an address set, a copy of the `Hints.forZones` field is made from each endpoint slice if one is present. This field is only present if it's set by the endpoint slice controller and comes with several ([safeguards][topology-aware-hints-safeguards]). To have the endpoint slice controller set the `forZones` field users will have to add the `service.kubernetes.io/topology-aware-hints=auto` annotation to the service.

After the endpoints have been translated into an address set and the endpoint translator's available endpoints have been updated, filtering is applied to ensure only the relevant sets of addresses are returned when a request is made.

For each potential address in the available endpoint set Linkerd returns a set of addresses whose consumption zone (zones in `forZones` field) matches that of the node's zone. By doing so Linkerd ensures communication is limited to endpoints that have been labeled by the endpoint slice controller for the same node the client is on and limits cross-node and cross-zone communication.


#Constraints
deusxanima marked this conversation as resolved.
Show resolved Hide resolved

There are a few ([contraints][topology-aware-hints-constraints]) that should be considered and reviewed before enabling topology aware hints on Linkerd. These include an assumption that incoming traffic will be roughly proportional to the capacity of the nodes in each zone, a caveat when using a horizontal pod autoscaler which may result in the HPA starting new pods in a different zone than the one seeing a traffic increase, and a reminder that the Kubernetes endpoint slice controller does not take in
:q
to account tolerations when deploying or calculating the proportions of each zone.
deusxanima marked this conversation as resolved.
Show resolved Hide resolved


#Confiring Topology Aware Routing
deusxanima marked this conversation as resolved.
Show resolved Hide resolved

Successful topology aware routing can be confirmed by looking at the Linkerd proxy logs for the relevant service. The logs should show a stream of messages similar to the ones below:

```
time="2021-08-27T14:04:35Z" level=info msg="Establishing watch on endpoint [default/nginx-deploy-svc:80]" addr=":8086" component=endpoints-watcher
time="2021-08-27T14:04:35Z" level=debug msg="Filtering through addresses that should be consumed by zone zone-b" addr=":8086" component=endpoint-translator remote="127.0.0.1:49846" service="nginx-deploy-svc.default.svc.cluster.local:80"
deusxanima marked this conversation as resolved.
Show resolved Hide resolved
```


[topology-aware-hints-safeguards]: https://kubernetes.io/docs/concepts/services-networking/topology-aware-hints/#safeguards
[topology-aware-hints-constraints]: https://kubernetes.io/docs/concepts/services-networking/topology-aware-hints/#constraints