From b6020137c0ca9adba7ff25d91573900177b37d7e Mon Sep 17 00:00:00 2001 From: deusxanima Date: Tue, 28 Feb 2023 11:37:52 -0500 Subject: [PATCH 1/9] Adding feature documentation and task instructions for topology aware hints Signed-off-by: Alen Haric --- .../2.12/features/topology-aware-hints.md | 21 ++++++++++ .../tasks/enabling-topology-aware-hints.md | 39 +++++++++++++++++++ 2 files changed, 60 insertions(+) create mode 100644 linkerd.io/content/2.12/features/topology-aware-hints.md create mode 100644 linkerd.io/content/2.12/tasks/enabling-topology-aware-hints.md diff --git a/linkerd.io/content/2.12/features/topology-aware-hints.md b/linkerd.io/content/2.12/features/topology-aware-hints.md new file mode 100644 index 0000000000..985353dd8e --- /dev/null +++ b/linkerd.io/content/2.12/features/topology-aware-hints.md @@ -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. + +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. + +{{< 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. + +{{< /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/ \ No newline at end of file diff --git a/linkerd.io/content/2.12/tasks/enabling-topology-aware-hints.md b/linkerd.io/content/2.12/tasks/enabling-topology-aware-hints.md new file mode 100644 index 0000000000..469d5d9a48 --- /dev/null +++ b/linkerd.io/content/2.12/tasks/enabling-topology-aware-hints.md @@ -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. +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. + +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 + +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. + + +#Confiring Topology Aware Routing + +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" +``` + + +[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 \ No newline at end of file From 7b2832b0ea06c00da402790db23bd03d059b3790 Mon Sep 17 00:00:00 2001 From: Alen Haric Date: Tue, 25 Apr 2023 15:24:05 -0400 Subject: [PATCH 2/9] cleaned up previously committed errors and modified phrasing as recommended by Flynn. Signed-off-by: Alen Haric --- .../2.12/features/topology-aware-hints.md | 6 +-- .../tasks/enabling-topology-aware-hints.md | 17 ++++---- .../2.13/features/topology-aware-hints.md | 21 ++++++++++ .../tasks/enabling-topology-aware-hints.md | 42 +++++++++++++++++++ 4 files changed, 76 insertions(+), 10 deletions(-) create mode 100644 linkerd.io/content/2.13/features/topology-aware-hints.md create mode 100644 linkerd.io/content/2.13/tasks/enabling-topology-aware-hints.md diff --git a/linkerd.io/content/2.12/features/topology-aware-hints.md b/linkerd.io/content/2.12/features/topology-aware-hints.md index 985353dd8e..f6baacabbb 100644 --- a/linkerd.io/content/2.12/features/topology-aware-hints.md +++ b/linkerd.io/content/2.12/features/topology-aware-hints.md @@ -6,13 +6,13 @@ aliases = [ ] +++ -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. +Kuberentes clusters are increasingly deployed in multi-zone environments with network traffic often relying on obscure 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 cluster that spans multiple zones. 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. -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. +The goal of topology aware hints is to to provide a simpler way for users to prefer endpoints by basing decisions solely off the node's `topology.kubernetes.io/zone` label. If a client is in `zone-a`, then it should prefer endpoints marked for use by clients in `zone-a`. When the feature is enabled and the label set, Linkerd's destination controller will attempt to find endpoints whose Hints.ForZones field matches the client's zone. {{< 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. +Topology aware hints require that the cluster have the `TopologyAwareHints` feature gate enabled, and that Linkerd's `endpointSlice` feature be turned on (this is the default starting with Linkerd stable-2.12). {{< /note >}} diff --git a/linkerd.io/content/2.12/tasks/enabling-topology-aware-hints.md b/linkerd.io/content/2.12/tasks/enabling-topology-aware-hints.md index 469d5d9a48..d1b89d622f 100644 --- a/linkerd.io/content/2.12/tasks/enabling-topology-aware-hints.md +++ b/linkerd.io/content/2.12/tasks/enabling-topology-aware-hints.md @@ -7,9 +7,9 @@ description = "Enable topology aware hints to allow Linkerd to intelligently cho 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. +1. `TopologyAwareHints` feature gate MUST be enabled on the Kubernetes cluster. 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. +3. Relevant Kubernetes services will need to be modified with the `service.kubernetes.io/topology-aware-hints=auto` annotation. 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. @@ -18,14 +18,17 @@ After the endpoints have been translated into an address set and the endpoint tr 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 +# Constraints -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. +There are a few ([contraints][topology-aware-hints-constraints]) that should be considered and reviewed before enabling topology aware hints on Linkerd. -#Confiring Topology Aware Routing +The main things to be aware of are: + +- Linkerd assumes that traffic to a given zone will be roughly proportional to the capacity of the nodes in the zone (which can be a concern when using horizontal pod autoscaling, as the HPA may start nodes in the "wrong" zone); and +- The Kubernetes endpoint slice controller does not take... + +# Configuring Topology Aware Routing 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: diff --git a/linkerd.io/content/2.13/features/topology-aware-hints.md b/linkerd.io/content/2.13/features/topology-aware-hints.md new file mode 100644 index 0000000000..f6baacabbb --- /dev/null +++ b/linkerd.io/content/2.13/features/topology-aware-hints.md @@ -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 obscure 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 cluster that spans multiple zones. 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. + +The goal of topology aware hints is to to provide a simpler way for users to prefer endpoints by basing decisions solely off the node's `topology.kubernetes.io/zone` label. If a client is in `zone-a`, then it should prefer endpoints marked for use by clients in `zone-a`. When the feature is enabled and the label set, Linkerd's destination controller will attempt to find endpoints whose Hints.ForZones field matches the client's zone. + +{{< note >}} + +Topology aware hints require that the cluster have the `TopologyAwareHints` feature gate enabled, and that Linkerd's `endpointSlice` feature be turned on (this is the default starting with Linkerd stable-2.12). + +{{< /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/ \ No newline at end of file diff --git a/linkerd.io/content/2.13/tasks/enabling-topology-aware-hints.md b/linkerd.io/content/2.13/tasks/enabling-topology-aware-hints.md new file mode 100644 index 0000000000..d1b89d622f --- /dev/null +++ b/linkerd.io/content/2.13/tasks/enabling-topology-aware-hints.md @@ -0,0 +1,42 @@ ++++ +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. `TopologyAwareHints` feature gate MUST be enabled on the Kubernetes cluster. +2. Each Kubernetes node should be labeled with the `"topology.kubernetes.io/zone` label. +3. Relevant Kubernetes services will need to be modified with the `service.kubernetes.io/topology-aware-hints=auto` annotation. + +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 + +There are a few ([contraints][topology-aware-hints-constraints]) that should be considered and reviewed before enabling topology aware hints on Linkerd. + + +The main things to be aware of are: + +- Linkerd assumes that traffic to a given zone will be roughly proportional to the capacity of the nodes in the zone (which can be a concern when using horizontal pod autoscaling, as the HPA may start nodes in the "wrong" zone); and +- The Kubernetes endpoint slice controller does not take... + +# Configuring Topology Aware Routing + +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" +``` + + +[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 \ No newline at end of file From b690e43cde430053f1d202ce5f4c83433c4950f6 Mon Sep 17 00:00:00 2001 From: Alen Haric Date: Tue, 25 Apr 2023 15:26:31 -0400 Subject: [PATCH 3/9] fixed minor typo Signed-off-by: Alen Haric --- linkerd.io/content/2.12/features/topology-aware-hints.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/linkerd.io/content/2.12/features/topology-aware-hints.md b/linkerd.io/content/2.12/features/topology-aware-hints.md index f6baacabbb..ae9276b3cc 100644 --- a/linkerd.io/content/2.12/features/topology-aware-hints.md +++ b/linkerd.io/content/2.12/features/topology-aware-hints.md @@ -6,7 +6,7 @@ aliases = [ ] +++ -Kuberentes clusters are increasingly deployed in multi-zone environments with network traffic often relying on obscure 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 cluster that spans multiple zones. 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. +Kubernetes clusters are increasingly deployed in multi-zone environments with network traffic often relying on obscure 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 cluster that spans multiple zones. 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. The goal of topology aware hints is to to provide a simpler way for users to prefer endpoints by basing decisions solely off the node's `topology.kubernetes.io/zone` label. If a client is in `zone-a`, then it should prefer endpoints marked for use by clients in `zone-a`. When the feature is enabled and the label set, Linkerd's destination controller will attempt to find endpoints whose Hints.ForZones field matches the client's zone. From b4585dcef5d74ff01e459c1c2864ea4a0afad191 Mon Sep 17 00:00:00 2001 From: Alen Haric Date: Tue, 25 Apr 2023 15:29:15 -0400 Subject: [PATCH 4/9] fixed missing code block notation on Hints.ForZones Signed-off-by: Alen Haric --- linkerd.io/content/2.12/features/topology-aware-hints.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/linkerd.io/content/2.12/features/topology-aware-hints.md b/linkerd.io/content/2.12/features/topology-aware-hints.md index ae9276b3cc..5990b5da5f 100644 --- a/linkerd.io/content/2.12/features/topology-aware-hints.md +++ b/linkerd.io/content/2.12/features/topology-aware-hints.md @@ -8,7 +8,7 @@ aliases = [ Kubernetes clusters are increasingly deployed in multi-zone environments with network traffic often relying on obscure 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 cluster that spans multiple zones. 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. -The goal of topology aware hints is to to provide a simpler way for users to prefer endpoints by basing decisions solely off the node's `topology.kubernetes.io/zone` label. If a client is in `zone-a`, then it should prefer endpoints marked for use by clients in `zone-a`. When the feature is enabled and the label set, Linkerd's destination controller will attempt to find endpoints whose Hints.ForZones field matches the client's zone. +The goal of topology aware hints is to to provide a simpler way for users to prefer endpoints by basing decisions solely off the node's `topology.kubernetes.io/zone` label. If a client is in `zone-a`, then it should prefer endpoints marked for use by clients in `zone-a`. When the feature is enabled and the label set, Linkerd's destination controller will attempt to find endpoints whose `Hints.ForZones` field matches the client's zone. {{< note >}} From 18b0ab1e75ce58094d8d4084c645845fbcbd9679 Mon Sep 17 00:00:00 2001 From: Flynn Date: Sun, 2 Feb 2025 21:38:43 -0500 Subject: [PATCH 5/9] Tweaks plus callouts for stable features in 2.16+ Signed-off-by: Flynn --- .../2.12/features/topology-aware-hints.md | 31 ++++++-- .../tasks/enabling-topology-aware-hints.md | 58 ++++++++++---- .../2.13/features/topology-aware-hints.md | 31 ++++++-- .../tasks/enabling-topology-aware-hints.md | 58 ++++++++++---- .../2.14/features/topology-aware-hints.md | 38 +++++++++ .../tasks/enabling-topology-aware-hints.md | 66 ++++++++++++++++ .../2.15/features/topology-aware-hints.md | 38 +++++++++ .../tasks/enabling-topology-aware-hints.md | 66 ++++++++++++++++ .../2.16/features/topology-aware-hints.md | 51 ++++++++++++ .../tasks/enabling-topology-aware-hints.md | 78 +++++++++++++++++++ .../2.17/features/topology-aware-hints.md | 51 ++++++++++++ .../tasks/enabling-topology-aware-hints.md | 78 +++++++++++++++++++ 12 files changed, 596 insertions(+), 48 deletions(-) create mode 100644 linkerd.io/content/2.14/features/topology-aware-hints.md create mode 100644 linkerd.io/content/2.14/tasks/enabling-topology-aware-hints.md create mode 100644 linkerd.io/content/2.15/features/topology-aware-hints.md create mode 100644 linkerd.io/content/2.15/tasks/enabling-topology-aware-hints.md create mode 100644 linkerd.io/content/2.16/features/topology-aware-hints.md create mode 100644 linkerd.io/content/2.16/tasks/enabling-topology-aware-hints.md create mode 100644 linkerd.io/content/2.17/features/topology-aware-hints.md create mode 100644 linkerd.io/content/2.17/tasks/enabling-topology-aware-hints.md diff --git a/linkerd.io/content/2.12/features/topology-aware-hints.md b/linkerd.io/content/2.12/features/topology-aware-hints.md index 5990b5da5f..90d2047d4b 100644 --- a/linkerd.io/content/2.12/features/topology-aware-hints.md +++ b/linkerd.io/content/2.12/features/topology-aware-hints.md @@ -6,16 +6,33 @@ aliases = [ ] +++ -Kubernetes clusters are increasingly deployed in multi-zone environments with network traffic often relying on obscure 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 cluster that spans multiple zones. 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. +Kubernetes clusters are increasingly deployed in multi-zone environments with +network traffic often relying on obscure 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 cluster that spans +multiple zones. 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. -The goal of topology aware hints is to to provide a simpler way for users to prefer endpoints by basing decisions solely off the node's `topology.kubernetes.io/zone` label. If a client is in `zone-a`, then it should prefer endpoints marked for use by clients in `zone-a`. When the feature is enabled and the label set, Linkerd's destination controller will attempt to find endpoints whose `Hints.ForZones` field matches the client's zone. +The goal of topology aware hints is to to provide a simpler way for users to +prefer endpoints by basing decisions solely off the node's +`topology.kubernetes.io/zone` label. If a client is in `zone-a`, then it +should prefer endpoints marked for use by clients in `zone-a`. When the +feature is enabled and the label set, Linkerd's destination controller will +attempt to find endpoints whose `Hints.ForZones` field matches the client's +zone. -{{< 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 require that the cluster have the `TopologyAwareHints` feature gate enabled, and that Linkerd's `endpointSlice` feature be turned on (this is the default starting with Linkerd stable-2.12). +[topology aware hints]: https://kubernetes.io/docs/concepts/services-networking/topology-aware-hints/ -{{< /note >}} +{{< 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 require that the cluster have the `TopologyAwareHints` +feature gate enabled, and that Linkerd's `endpointSlice` feature be turned on +(this is the default starting with Linkerd stable-2.12). -[topology aware hints]: https://kubernetes.io/docs/concepts/services-networking/topology-aware-hints/ \ No newline at end of file +{{< /note >}} diff --git a/linkerd.io/content/2.12/tasks/enabling-topology-aware-hints.md b/linkerd.io/content/2.12/tasks/enabling-topology-aware-hints.md index d1b89d622f..3394b576df 100644 --- a/linkerd.io/content/2.12/tasks/enabling-topology-aware-hints.md +++ b/linkerd.io/content/2.12/tasks/enabling-topology-aware-hints.md @@ -3,40 +3,64 @@ 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. +[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. `TopologyAwareHints` feature gate MUST be enabled on the Kubernetes cluster. -2. Each Kubernetes node should be labeled with the `"topology.kubernetes.io/zone` label. -3. Relevant Kubernetes services will need to be modified with the `service.kubernetes.io/topology-aware-hints=auto` annotation. - -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. - +1. `TopologyAwareHints` feature gate MUST be enabled on the Kubernetes + cluster. +2. Each Kubernetes node should be labeled with the + `"topology.kubernetes.io/zone` label. +3. Relevant Kubernetes services will need to be modified with the + `service.kubernetes.io/topology-aware-hints=auto` annotation. + +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 there are several +[safeguards][topology-aware-hints-safeguards] that Kubernetes checks before +setting it. 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 -There are a few ([contraints][topology-aware-hints-constraints]) that should be considered and reviewed before enabling topology aware hints on Linkerd. - +Kubernetes places some [constraints][topology-aware-hints-constraints] on +topology aware hints that you should review before enabling topology aware +hints on Linkerd. The main things to be aware of are: -- Linkerd assumes that traffic to a given zone will be roughly proportional to the capacity of the nodes in the zone (which can be a concern when using horizontal pod autoscaling, as the HPA may start nodes in the "wrong" zone); and +- Linkerd assumes that traffic to a given zone will be roughly proportional to + the capacity of the nodes in the zone (which can be a concern when using + horizontal pod autoscaling, as the HPA may start nodes in the "wrong" zone); + and - The Kubernetes endpoint slice controller does not take... # Configuring Topology Aware Routing -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: +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" ``` - [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 \ No newline at end of file +[topology-aware-hints-constraints]: https://kubernetes.io/docs/concepts/services-networking/topology-aware-hints/#constraints diff --git a/linkerd.io/content/2.13/features/topology-aware-hints.md b/linkerd.io/content/2.13/features/topology-aware-hints.md index f6baacabbb..90d2047d4b 100644 --- a/linkerd.io/content/2.13/features/topology-aware-hints.md +++ b/linkerd.io/content/2.13/features/topology-aware-hints.md @@ -6,16 +6,33 @@ aliases = [ ] +++ -Kuberentes clusters are increasingly deployed in multi-zone environments with network traffic often relying on obscure 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 cluster that spans multiple zones. 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. +Kubernetes clusters are increasingly deployed in multi-zone environments with +network traffic often relying on obscure 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 cluster that spans +multiple zones. 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. -The goal of topology aware hints is to to provide a simpler way for users to prefer endpoints by basing decisions solely off the node's `topology.kubernetes.io/zone` label. If a client is in `zone-a`, then it should prefer endpoints marked for use by clients in `zone-a`. When the feature is enabled and the label set, Linkerd's destination controller will attempt to find endpoints whose Hints.ForZones field matches the client's zone. +The goal of topology aware hints is to to provide a simpler way for users to +prefer endpoints by basing decisions solely off the node's +`topology.kubernetes.io/zone` label. If a client is in `zone-a`, then it +should prefer endpoints marked for use by clients in `zone-a`. When the +feature is enabled and the label set, Linkerd's destination controller will +attempt to find endpoints whose `Hints.ForZones` field matches the client's +zone. -{{< 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 require that the cluster have the `TopologyAwareHints` feature gate enabled, and that Linkerd's `endpointSlice` feature be turned on (this is the default starting with Linkerd stable-2.12). +[topology aware hints]: https://kubernetes.io/docs/concepts/services-networking/topology-aware-hints/ -{{< /note >}} +{{< 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 require that the cluster have the `TopologyAwareHints` +feature gate enabled, and that Linkerd's `endpointSlice` feature be turned on +(this is the default starting with Linkerd stable-2.12). -[topology aware hints]: https://kubernetes.io/docs/concepts/services-networking/topology-aware-hints/ \ No newline at end of file +{{< /note >}} diff --git a/linkerd.io/content/2.13/tasks/enabling-topology-aware-hints.md b/linkerd.io/content/2.13/tasks/enabling-topology-aware-hints.md index d1b89d622f..3394b576df 100644 --- a/linkerd.io/content/2.13/tasks/enabling-topology-aware-hints.md +++ b/linkerd.io/content/2.13/tasks/enabling-topology-aware-hints.md @@ -3,40 +3,64 @@ 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. +[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. `TopologyAwareHints` feature gate MUST be enabled on the Kubernetes cluster. -2. Each Kubernetes node should be labeled with the `"topology.kubernetes.io/zone` label. -3. Relevant Kubernetes services will need to be modified with the `service.kubernetes.io/topology-aware-hints=auto` annotation. - -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. - +1. `TopologyAwareHints` feature gate MUST be enabled on the Kubernetes + cluster. +2. Each Kubernetes node should be labeled with the + `"topology.kubernetes.io/zone` label. +3. Relevant Kubernetes services will need to be modified with the + `service.kubernetes.io/topology-aware-hints=auto` annotation. + +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 there are several +[safeguards][topology-aware-hints-safeguards] that Kubernetes checks before +setting it. 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 -There are a few ([contraints][topology-aware-hints-constraints]) that should be considered and reviewed before enabling topology aware hints on Linkerd. - +Kubernetes places some [constraints][topology-aware-hints-constraints] on +topology aware hints that you should review before enabling topology aware +hints on Linkerd. The main things to be aware of are: -- Linkerd assumes that traffic to a given zone will be roughly proportional to the capacity of the nodes in the zone (which can be a concern when using horizontal pod autoscaling, as the HPA may start nodes in the "wrong" zone); and +- Linkerd assumes that traffic to a given zone will be roughly proportional to + the capacity of the nodes in the zone (which can be a concern when using + horizontal pod autoscaling, as the HPA may start nodes in the "wrong" zone); + and - The Kubernetes endpoint slice controller does not take... # Configuring Topology Aware Routing -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: +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" ``` - [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 \ No newline at end of file +[topology-aware-hints-constraints]: https://kubernetes.io/docs/concepts/services-networking/topology-aware-hints/#constraints diff --git a/linkerd.io/content/2.14/features/topology-aware-hints.md b/linkerd.io/content/2.14/features/topology-aware-hints.md new file mode 100644 index 0000000000..90d2047d4b --- /dev/null +++ b/linkerd.io/content/2.14/features/topology-aware-hints.md @@ -0,0 +1,38 @@ ++++ +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/" +] ++++ + +Kubernetes clusters are increasingly deployed in multi-zone environments with +network traffic often relying on obscure 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 cluster that spans +multiple zones. 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. + +The goal of topology aware hints is to to provide a simpler way for users to +prefer endpoints by basing decisions solely off the node's +`topology.kubernetes.io/zone` label. If a client is in `zone-a`, then it +should prefer endpoints marked for use by clients in `zone-a`. When the +feature is enabled and the label set, Linkerd's destination controller will +attempt to find endpoints whose `Hints.ForZones` field matches the client's +zone. + +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/ + +{{< note >}} + +Topology aware hints require that the cluster have the `TopologyAwareHints` +feature gate enabled, and that Linkerd's `endpointSlice` feature be turned on +(this is the default starting with Linkerd stable-2.12). + +{{< /note >}} diff --git a/linkerd.io/content/2.14/tasks/enabling-topology-aware-hints.md b/linkerd.io/content/2.14/tasks/enabling-topology-aware-hints.md new file mode 100644 index 0000000000..3394b576df --- /dev/null +++ b/linkerd.io/content/2.14/tasks/enabling-topology-aware-hints.md @@ -0,0 +1,66 @@ ++++ +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. `TopologyAwareHints` feature gate MUST be enabled on the Kubernetes + cluster. +2. Each Kubernetes node should be labeled with the + `"topology.kubernetes.io/zone` label. +3. Relevant Kubernetes services will need to be modified with the + `service.kubernetes.io/topology-aware-hints=auto` annotation. + +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 there are several +[safeguards][topology-aware-hints-safeguards] that Kubernetes checks before +setting it. 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 + +Kubernetes places some [constraints][topology-aware-hints-constraints] on +topology aware hints that you should review before enabling topology aware +hints on Linkerd. + +The main things to be aware of are: + +- Linkerd assumes that traffic to a given zone will be roughly proportional to + the capacity of the nodes in the zone (which can be a concern when using + horizontal pod autoscaling, as the HPA may start nodes in the "wrong" zone); + and +- The Kubernetes endpoint slice controller does not take... + +# Configuring Topology Aware Routing + +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" +``` + +[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 diff --git a/linkerd.io/content/2.15/features/topology-aware-hints.md b/linkerd.io/content/2.15/features/topology-aware-hints.md new file mode 100644 index 0000000000..90d2047d4b --- /dev/null +++ b/linkerd.io/content/2.15/features/topology-aware-hints.md @@ -0,0 +1,38 @@ ++++ +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/" +] ++++ + +Kubernetes clusters are increasingly deployed in multi-zone environments with +network traffic often relying on obscure 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 cluster that spans +multiple zones. 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. + +The goal of topology aware hints is to to provide a simpler way for users to +prefer endpoints by basing decisions solely off the node's +`topology.kubernetes.io/zone` label. If a client is in `zone-a`, then it +should prefer endpoints marked for use by clients in `zone-a`. When the +feature is enabled and the label set, Linkerd's destination controller will +attempt to find endpoints whose `Hints.ForZones` field matches the client's +zone. + +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/ + +{{< note >}} + +Topology aware hints require that the cluster have the `TopologyAwareHints` +feature gate enabled, and that Linkerd's `endpointSlice` feature be turned on +(this is the default starting with Linkerd stable-2.12). + +{{< /note >}} diff --git a/linkerd.io/content/2.15/tasks/enabling-topology-aware-hints.md b/linkerd.io/content/2.15/tasks/enabling-topology-aware-hints.md new file mode 100644 index 0000000000..3394b576df --- /dev/null +++ b/linkerd.io/content/2.15/tasks/enabling-topology-aware-hints.md @@ -0,0 +1,66 @@ ++++ +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. `TopologyAwareHints` feature gate MUST be enabled on the Kubernetes + cluster. +2. Each Kubernetes node should be labeled with the + `"topology.kubernetes.io/zone` label. +3. Relevant Kubernetes services will need to be modified with the + `service.kubernetes.io/topology-aware-hints=auto` annotation. + +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 there are several +[safeguards][topology-aware-hints-safeguards] that Kubernetes checks before +setting it. 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 + +Kubernetes places some [constraints][topology-aware-hints-constraints] on +topology aware hints that you should review before enabling topology aware +hints on Linkerd. + +The main things to be aware of are: + +- Linkerd assumes that traffic to a given zone will be roughly proportional to + the capacity of the nodes in the zone (which can be a concern when using + horizontal pod autoscaling, as the HPA may start nodes in the "wrong" zone); + and +- The Kubernetes endpoint slice controller does not take... + +# Configuring Topology Aware Routing + +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" +``` + +[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 diff --git a/linkerd.io/content/2.16/features/topology-aware-hints.md b/linkerd.io/content/2.16/features/topology-aware-hints.md new file mode 100644 index 0000000000..6ad2739844 --- /dev/null +++ b/linkerd.io/content/2.16/features/topology-aware-hints.md @@ -0,0 +1,51 @@ ++++ +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/" +] ++++ + +Kubernetes clusters are increasingly deployed in multi-zone environments with +network traffic often relying on obscure 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 cluster that spans +multiple zones. 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. + +The goal of topology aware hints is to to provide a simpler way for users to +prefer endpoints by basing decisions solely off the node's +`topology.kubernetes.io/zone` label. If a client is in `zone-a`, then it +should prefer endpoints marked for use by clients in `zone-a`. When the +feature is enabled and the label set, Linkerd's destination controller will +attempt to find endpoints whose `Hints.ForZones` field matches the client's +zone. + +{{< note >}} + +If you're using a [stable distribution](/releases/#stable) of Linkerd, it may +have additional features related to topology-aware routing (for example, Buoyant Enterprise for +Linkerd and its HAZL +feature). You can find more information about the different kinds of Linkerd +releases on the [Releases and Versions](/releases/) page. + +{{< /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/ + +{{< note >}} + +Topology aware hints require that the cluster have the `TopologyAwareHints` +feature gate enabled, and that Linkerd's `endpointSlice` feature be turned on +(this is the default starting with Linkerd stable-2.12). + +{{< /note >}} + diff --git a/linkerd.io/content/2.16/tasks/enabling-topology-aware-hints.md b/linkerd.io/content/2.16/tasks/enabling-topology-aware-hints.md new file mode 100644 index 0000000000..18baf7e67e --- /dev/null +++ b/linkerd.io/content/2.16/tasks/enabling-topology-aware-hints.md @@ -0,0 +1,78 @@ ++++ +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. + +{{< note >}} + +If you're using a [stable distribution](/releases/#stable) of Linkerd, it may +have additional features related to topology-aware routing (for example, Buoyant Enterprise for +Linkerd and its HAZL +feature). You can find more information about the different kinds of Linkerd +releases on the [Releases and Versions](/releases/) page. + +{{< /note >}} + +There are three requirements to successfully enabling topology aware hints with Linkerd: + +1. `TopologyAwareHints` feature gate MUST be enabled on the Kubernetes + cluster. +2. Each Kubernetes node should be labeled with the + `"topology.kubernetes.io/zone` label. +3. Relevant Kubernetes services will need to be modified with the + `service.kubernetes.io/topology-aware-hints=auto` annotation. + +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 there are several +[safeguards][topology-aware-hints-safeguards] that Kubernetes checks before +setting it. 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 + +Kubernetes places some [constraints][topology-aware-hints-constraints] on +topology aware hints that you should review before enabling topology aware +hints on Linkerd. + +The main things to be aware of are: + +- Linkerd assumes that traffic to a given zone will be roughly proportional to + the capacity of the nodes in the zone (which can be a concern when using + horizontal pod autoscaling, as the HPA may start nodes in the "wrong" zone); + and +- The Kubernetes endpoint slice controller does not take... + +# Configuring Topology Aware Routing + +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" +``` + +[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 diff --git a/linkerd.io/content/2.17/features/topology-aware-hints.md b/linkerd.io/content/2.17/features/topology-aware-hints.md new file mode 100644 index 0000000000..6ad2739844 --- /dev/null +++ b/linkerd.io/content/2.17/features/topology-aware-hints.md @@ -0,0 +1,51 @@ ++++ +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/" +] ++++ + +Kubernetes clusters are increasingly deployed in multi-zone environments with +network traffic often relying on obscure 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 cluster that spans +multiple zones. 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. + +The goal of topology aware hints is to to provide a simpler way for users to +prefer endpoints by basing decisions solely off the node's +`topology.kubernetes.io/zone` label. If a client is in `zone-a`, then it +should prefer endpoints marked for use by clients in `zone-a`. When the +feature is enabled and the label set, Linkerd's destination controller will +attempt to find endpoints whose `Hints.ForZones` field matches the client's +zone. + +{{< note >}} + +If you're using a [stable distribution](/releases/#stable) of Linkerd, it may +have additional features related to topology-aware routing (for example, Buoyant Enterprise for +Linkerd and its HAZL +feature). You can find more information about the different kinds of Linkerd +releases on the [Releases and Versions](/releases/) page. + +{{< /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/ + +{{< note >}} + +Topology aware hints require that the cluster have the `TopologyAwareHints` +feature gate enabled, and that Linkerd's `endpointSlice` feature be turned on +(this is the default starting with Linkerd stable-2.12). + +{{< /note >}} + diff --git a/linkerd.io/content/2.17/tasks/enabling-topology-aware-hints.md b/linkerd.io/content/2.17/tasks/enabling-topology-aware-hints.md new file mode 100644 index 0000000000..18baf7e67e --- /dev/null +++ b/linkerd.io/content/2.17/tasks/enabling-topology-aware-hints.md @@ -0,0 +1,78 @@ ++++ +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. + +{{< note >}} + +If you're using a [stable distribution](/releases/#stable) of Linkerd, it may +have additional features related to topology-aware routing (for example, Buoyant Enterprise for +Linkerd and its HAZL +feature). You can find more information about the different kinds of Linkerd +releases on the [Releases and Versions](/releases/) page. + +{{< /note >}} + +There are three requirements to successfully enabling topology aware hints with Linkerd: + +1. `TopologyAwareHints` feature gate MUST be enabled on the Kubernetes + cluster. +2. Each Kubernetes node should be labeled with the + `"topology.kubernetes.io/zone` label. +3. Relevant Kubernetes services will need to be modified with the + `service.kubernetes.io/topology-aware-hints=auto` annotation. + +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 there are several +[safeguards][topology-aware-hints-safeguards] that Kubernetes checks before +setting it. 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 + +Kubernetes places some [constraints][topology-aware-hints-constraints] on +topology aware hints that you should review before enabling topology aware +hints on Linkerd. + +The main things to be aware of are: + +- Linkerd assumes that traffic to a given zone will be roughly proportional to + the capacity of the nodes in the zone (which can be a concern when using + horizontal pod autoscaling, as the HPA may start nodes in the "wrong" zone); + and +- The Kubernetes endpoint slice controller does not take... + +# Configuring Topology Aware Routing + +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" +``` + +[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 From c72fdf2847f149c585c6b8626119ffc49e6fd9c6 Mon Sep 17 00:00:00 2001 From: Flynn Date: Sun, 2 Feb 2025 22:05:14 -0500 Subject: [PATCH 6/9] Lint fixes Signed-off-by: Flynn --- .../content/2.12/features/topology-aware-hints.md | 2 +- .../2.12/tasks/enabling-topology-aware-hints.md | 12 ++++++------ .../content/2.13/features/topology-aware-hints.md | 2 +- .../2.13/tasks/enabling-topology-aware-hints.md | 12 ++++++------ .../content/2.14/features/topology-aware-hints.md | 2 +- .../2.14/tasks/enabling-topology-aware-hints.md | 12 ++++++------ .../content/2.15/features/topology-aware-hints.md | 2 +- .../2.15/tasks/enabling-topology-aware-hints.md | 12 ++++++------ .../content/2.16/features/topology-aware-hints.md | 3 +-- .../2.16/tasks/enabling-topology-aware-hints.md | 8 ++++---- .../content/2.17/features/topology-aware-hints.md | 3 +-- .../2.17/tasks/enabling-topology-aware-hints.md | 8 ++++---- 12 files changed, 38 insertions(+), 40 deletions(-) diff --git a/linkerd.io/content/2.12/features/topology-aware-hints.md b/linkerd.io/content/2.12/features/topology-aware-hints.md index 90d2047d4b..a96ac48c81 100644 --- a/linkerd.io/content/2.12/features/topology-aware-hints.md +++ b/linkerd.io/content/2.12/features/topology-aware-hints.md @@ -25,7 +25,7 @@ attempt to find endpoints whose `Hints.ForZones` field matches the client's zone. To get started with topology aware hints take a look at the [enabling topology -aware hints](../tasks/enabling-topology-aware-hints/) task documentation. +aware hints](../../tasks/enabling-topology-aware-hints/) task documentation. [topology aware hints]: https://kubernetes.io/docs/concepts/services-networking/topology-aware-hints/ diff --git a/linkerd.io/content/2.12/tasks/enabling-topology-aware-hints.md b/linkerd.io/content/2.12/tasks/enabling-topology-aware-hints.md index 3394b576df..0c1c37a08c 100644 --- a/linkerd.io/content/2.12/tasks/enabling-topology-aware-hints.md +++ b/linkerd.io/content/2.12/tasks/enabling-topology-aware-hints.md @@ -3,9 +3,9 @@ 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 +[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: @@ -37,7 +37,7 @@ 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 +## Constraints Kubernetes places some [constraints][topology-aware-hints-constraints] on topology aware hints that you should review before enabling topology aware @@ -51,13 +51,13 @@ The main things to be aware of are: and - The Kubernetes endpoint slice controller does not take... -# Configuring Topology Aware Routing +## Configuring Topology Aware Routing 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: -``` +```text 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" ``` diff --git a/linkerd.io/content/2.13/features/topology-aware-hints.md b/linkerd.io/content/2.13/features/topology-aware-hints.md index 90d2047d4b..a96ac48c81 100644 --- a/linkerd.io/content/2.13/features/topology-aware-hints.md +++ b/linkerd.io/content/2.13/features/topology-aware-hints.md @@ -25,7 +25,7 @@ attempt to find endpoints whose `Hints.ForZones` field matches the client's zone. To get started with topology aware hints take a look at the [enabling topology -aware hints](../tasks/enabling-topology-aware-hints/) task documentation. +aware hints](../../tasks/enabling-topology-aware-hints/) task documentation. [topology aware hints]: https://kubernetes.io/docs/concepts/services-networking/topology-aware-hints/ diff --git a/linkerd.io/content/2.13/tasks/enabling-topology-aware-hints.md b/linkerd.io/content/2.13/tasks/enabling-topology-aware-hints.md index 3394b576df..0c1c37a08c 100644 --- a/linkerd.io/content/2.13/tasks/enabling-topology-aware-hints.md +++ b/linkerd.io/content/2.13/tasks/enabling-topology-aware-hints.md @@ -3,9 +3,9 @@ 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 +[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: @@ -37,7 +37,7 @@ 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 +## Constraints Kubernetes places some [constraints][topology-aware-hints-constraints] on topology aware hints that you should review before enabling topology aware @@ -51,13 +51,13 @@ The main things to be aware of are: and - The Kubernetes endpoint slice controller does not take... -# Configuring Topology Aware Routing +## Configuring Topology Aware Routing 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: -``` +```text 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" ``` diff --git a/linkerd.io/content/2.14/features/topology-aware-hints.md b/linkerd.io/content/2.14/features/topology-aware-hints.md index 90d2047d4b..a96ac48c81 100644 --- a/linkerd.io/content/2.14/features/topology-aware-hints.md +++ b/linkerd.io/content/2.14/features/topology-aware-hints.md @@ -25,7 +25,7 @@ attempt to find endpoints whose `Hints.ForZones` field matches the client's zone. To get started with topology aware hints take a look at the [enabling topology -aware hints](../tasks/enabling-topology-aware-hints/) task documentation. +aware hints](../../tasks/enabling-topology-aware-hints/) task documentation. [topology aware hints]: https://kubernetes.io/docs/concepts/services-networking/topology-aware-hints/ diff --git a/linkerd.io/content/2.14/tasks/enabling-topology-aware-hints.md b/linkerd.io/content/2.14/tasks/enabling-topology-aware-hints.md index 3394b576df..0c1c37a08c 100644 --- a/linkerd.io/content/2.14/tasks/enabling-topology-aware-hints.md +++ b/linkerd.io/content/2.14/tasks/enabling-topology-aware-hints.md @@ -3,9 +3,9 @@ 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 +[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: @@ -37,7 +37,7 @@ 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 +## Constraints Kubernetes places some [constraints][topology-aware-hints-constraints] on topology aware hints that you should review before enabling topology aware @@ -51,13 +51,13 @@ The main things to be aware of are: and - The Kubernetes endpoint slice controller does not take... -# Configuring Topology Aware Routing +## Configuring Topology Aware Routing 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: -``` +```text 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" ``` diff --git a/linkerd.io/content/2.15/features/topology-aware-hints.md b/linkerd.io/content/2.15/features/topology-aware-hints.md index 90d2047d4b..a96ac48c81 100644 --- a/linkerd.io/content/2.15/features/topology-aware-hints.md +++ b/linkerd.io/content/2.15/features/topology-aware-hints.md @@ -25,7 +25,7 @@ attempt to find endpoints whose `Hints.ForZones` field matches the client's zone. To get started with topology aware hints take a look at the [enabling topology -aware hints](../tasks/enabling-topology-aware-hints/) task documentation. +aware hints](../../tasks/enabling-topology-aware-hints/) task documentation. [topology aware hints]: https://kubernetes.io/docs/concepts/services-networking/topology-aware-hints/ diff --git a/linkerd.io/content/2.15/tasks/enabling-topology-aware-hints.md b/linkerd.io/content/2.15/tasks/enabling-topology-aware-hints.md index 3394b576df..0c1c37a08c 100644 --- a/linkerd.io/content/2.15/tasks/enabling-topology-aware-hints.md +++ b/linkerd.io/content/2.15/tasks/enabling-topology-aware-hints.md @@ -3,9 +3,9 @@ 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 +[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: @@ -37,7 +37,7 @@ 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 +## Constraints Kubernetes places some [constraints][topology-aware-hints-constraints] on topology aware hints that you should review before enabling topology aware @@ -51,13 +51,13 @@ The main things to be aware of are: and - The Kubernetes endpoint slice controller does not take... -# Configuring Topology Aware Routing +## Configuring Topology Aware Routing 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: -``` +```text 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" ``` diff --git a/linkerd.io/content/2.16/features/topology-aware-hints.md b/linkerd.io/content/2.16/features/topology-aware-hints.md index 6ad2739844..4903e0e8d2 100644 --- a/linkerd.io/content/2.16/features/topology-aware-hints.md +++ b/linkerd.io/content/2.16/features/topology-aware-hints.md @@ -37,7 +37,7 @@ releases on the [Releases and Versions](/releases/) page. {{< /note >}} To get started with topology aware hints take a look at the [enabling topology -aware hints](../tasks/enabling-topology-aware-hints/) task documentation. +aware hints](../../tasks/enabling-topology-aware-hints/) task documentation. [topology aware hints]: https://kubernetes.io/docs/concepts/services-networking/topology-aware-hints/ @@ -48,4 +48,3 @@ feature gate enabled, and that Linkerd's `endpointSlice` feature be turned on (this is the default starting with Linkerd stable-2.12). {{< /note >}} - diff --git a/linkerd.io/content/2.16/tasks/enabling-topology-aware-hints.md b/linkerd.io/content/2.16/tasks/enabling-topology-aware-hints.md index 18baf7e67e..f681823a38 100644 --- a/linkerd.io/content/2.16/tasks/enabling-topology-aware-hints.md +++ b/linkerd.io/content/2.16/tasks/enabling-topology-aware-hints.md @@ -3,7 +3,7 @@ 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 +[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. @@ -49,7 +49,7 @@ 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 +## Constraints Kubernetes places some [constraints][topology-aware-hints-constraints] on topology aware hints that you should review before enabling topology aware @@ -63,13 +63,13 @@ The main things to be aware of are: and - The Kubernetes endpoint slice controller does not take... -# Configuring Topology Aware Routing +## Configuring Topology Aware Routing 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: -``` +```text 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" ``` diff --git a/linkerd.io/content/2.17/features/topology-aware-hints.md b/linkerd.io/content/2.17/features/topology-aware-hints.md index 6ad2739844..4903e0e8d2 100644 --- a/linkerd.io/content/2.17/features/topology-aware-hints.md +++ b/linkerd.io/content/2.17/features/topology-aware-hints.md @@ -37,7 +37,7 @@ releases on the [Releases and Versions](/releases/) page. {{< /note >}} To get started with topology aware hints take a look at the [enabling topology -aware hints](../tasks/enabling-topology-aware-hints/) task documentation. +aware hints](../../tasks/enabling-topology-aware-hints/) task documentation. [topology aware hints]: https://kubernetes.io/docs/concepts/services-networking/topology-aware-hints/ @@ -48,4 +48,3 @@ feature gate enabled, and that Linkerd's `endpointSlice` feature be turned on (this is the default starting with Linkerd stable-2.12). {{< /note >}} - diff --git a/linkerd.io/content/2.17/tasks/enabling-topology-aware-hints.md b/linkerd.io/content/2.17/tasks/enabling-topology-aware-hints.md index 18baf7e67e..f681823a38 100644 --- a/linkerd.io/content/2.17/tasks/enabling-topology-aware-hints.md +++ b/linkerd.io/content/2.17/tasks/enabling-topology-aware-hints.md @@ -3,7 +3,7 @@ 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 +[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. @@ -49,7 +49,7 @@ 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 +## Constraints Kubernetes places some [constraints][topology-aware-hints-constraints] on topology aware hints that you should review before enabling topology aware @@ -63,13 +63,13 @@ The main things to be aware of are: and - The Kubernetes endpoint slice controller does not take... -# Configuring Topology Aware Routing +## Configuring Topology Aware Routing 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: -``` +```text 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" ``` From 3e2484753d65cd717d84d5850aa97b5d45c48c80 Mon Sep 17 00:00:00 2001 From: Flynn Date: Mon, 3 Feb 2025 13:55:29 -0500 Subject: [PATCH 7/9] Fix front matter Signed-off-by: Flynn --- .../content/2.12/features/topology-aware-hints.md | 12 +++++------- .../2.12/tasks/enabling-topology-aware-hints.md | 9 +++++---- .../content/2.13/features/topology-aware-hints.md | 12 +++++------- .../2.13/tasks/enabling-topology-aware-hints.md | 9 +++++---- .../content/2.14/features/topology-aware-hints.md | 12 +++++------- .../2.14/tasks/enabling-topology-aware-hints.md | 9 +++++---- .../content/2.15/features/topology-aware-hints.md | 12 +++++------- .../2.15/tasks/enabling-topology-aware-hints.md | 9 +++++---- .../content/2.16/features/topology-aware-hints.md | 12 +++++------- .../2.16/tasks/enabling-topology-aware-hints.md | 9 +++++---- .../content/2.17/features/topology-aware-hints.md | 12 +++++------- .../2.17/tasks/enabling-topology-aware-hints.md | 9 +++++---- 12 files changed, 60 insertions(+), 66 deletions(-) diff --git a/linkerd.io/content/2.12/features/topology-aware-hints.md b/linkerd.io/content/2.12/features/topology-aware-hints.md index a96ac48c81..2cd2eb1a14 100644 --- a/linkerd.io/content/2.12/features/topology-aware-hints.md +++ b/linkerd.io/content/2.12/features/topology-aware-hints.md @@ -1,10 +1,8 @@ -+++ -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/" -] -+++ +--- +title: Topology Aware Hints +description: |- + Linkerd's implementation of Kubernetes topology aware hints enables endpoint consumption based on a node's zone label. +--- Kubernetes clusters are increasingly deployed in multi-zone environments with network traffic often relying on obscure endpoint matching and routing for a diff --git a/linkerd.io/content/2.12/tasks/enabling-topology-aware-hints.md b/linkerd.io/content/2.12/tasks/enabling-topology-aware-hints.md index 0c1c37a08c..cbbd82e50e 100644 --- a/linkerd.io/content/2.12/tasks/enabling-topology-aware-hints.md +++ b/linkerd.io/content/2.12/tasks/enabling-topology-aware-hints.md @@ -1,7 +1,8 @@ -+++ -title = "Enabling Topology Aware Hints" -description = "Enable topology aware hints to allow Linkerd to intelligently choose same-zone endpoints" -+++ +--- +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 diff --git a/linkerd.io/content/2.13/features/topology-aware-hints.md b/linkerd.io/content/2.13/features/topology-aware-hints.md index a96ac48c81..2cd2eb1a14 100644 --- a/linkerd.io/content/2.13/features/topology-aware-hints.md +++ b/linkerd.io/content/2.13/features/topology-aware-hints.md @@ -1,10 +1,8 @@ -+++ -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/" -] -+++ +--- +title: Topology Aware Hints +description: |- + Linkerd's implementation of Kubernetes topology aware hints enables endpoint consumption based on a node's zone label. +--- Kubernetes clusters are increasingly deployed in multi-zone environments with network traffic often relying on obscure endpoint matching and routing for a diff --git a/linkerd.io/content/2.13/tasks/enabling-topology-aware-hints.md b/linkerd.io/content/2.13/tasks/enabling-topology-aware-hints.md index 0c1c37a08c..cbbd82e50e 100644 --- a/linkerd.io/content/2.13/tasks/enabling-topology-aware-hints.md +++ b/linkerd.io/content/2.13/tasks/enabling-topology-aware-hints.md @@ -1,7 +1,8 @@ -+++ -title = "Enabling Topology Aware Hints" -description = "Enable topology aware hints to allow Linkerd to intelligently choose same-zone endpoints" -+++ +--- +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 diff --git a/linkerd.io/content/2.14/features/topology-aware-hints.md b/linkerd.io/content/2.14/features/topology-aware-hints.md index a96ac48c81..2cd2eb1a14 100644 --- a/linkerd.io/content/2.14/features/topology-aware-hints.md +++ b/linkerd.io/content/2.14/features/topology-aware-hints.md @@ -1,10 +1,8 @@ -+++ -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/" -] -+++ +--- +title: Topology Aware Hints +description: |- + Linkerd's implementation of Kubernetes topology aware hints enables endpoint consumption based on a node's zone label. +--- Kubernetes clusters are increasingly deployed in multi-zone environments with network traffic often relying on obscure endpoint matching and routing for a diff --git a/linkerd.io/content/2.14/tasks/enabling-topology-aware-hints.md b/linkerd.io/content/2.14/tasks/enabling-topology-aware-hints.md index 0c1c37a08c..cbbd82e50e 100644 --- a/linkerd.io/content/2.14/tasks/enabling-topology-aware-hints.md +++ b/linkerd.io/content/2.14/tasks/enabling-topology-aware-hints.md @@ -1,7 +1,8 @@ -+++ -title = "Enabling Topology Aware Hints" -description = "Enable topology aware hints to allow Linkerd to intelligently choose same-zone endpoints" -+++ +--- +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 diff --git a/linkerd.io/content/2.15/features/topology-aware-hints.md b/linkerd.io/content/2.15/features/topology-aware-hints.md index a96ac48c81..2cd2eb1a14 100644 --- a/linkerd.io/content/2.15/features/topology-aware-hints.md +++ b/linkerd.io/content/2.15/features/topology-aware-hints.md @@ -1,10 +1,8 @@ -+++ -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/" -] -+++ +--- +title: Topology Aware Hints +description: |- + Linkerd's implementation of Kubernetes topology aware hints enables endpoint consumption based on a node's zone label. +--- Kubernetes clusters are increasingly deployed in multi-zone environments with network traffic often relying on obscure endpoint matching and routing for a diff --git a/linkerd.io/content/2.15/tasks/enabling-topology-aware-hints.md b/linkerd.io/content/2.15/tasks/enabling-topology-aware-hints.md index 0c1c37a08c..cbbd82e50e 100644 --- a/linkerd.io/content/2.15/tasks/enabling-topology-aware-hints.md +++ b/linkerd.io/content/2.15/tasks/enabling-topology-aware-hints.md @@ -1,7 +1,8 @@ -+++ -title = "Enabling Topology Aware Hints" -description = "Enable topology aware hints to allow Linkerd to intelligently choose same-zone endpoints" -+++ +--- +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 diff --git a/linkerd.io/content/2.16/features/topology-aware-hints.md b/linkerd.io/content/2.16/features/topology-aware-hints.md index 4903e0e8d2..4878f692f1 100644 --- a/linkerd.io/content/2.16/features/topology-aware-hints.md +++ b/linkerd.io/content/2.16/features/topology-aware-hints.md @@ -1,10 +1,8 @@ -+++ -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/" -] -+++ +--- +title: Topology Aware Hints +description: |- + Linkerd's implementation of Kubernetes topology aware hints enables endpoint consumption based on a node's zone label. +--- Kubernetes clusters are increasingly deployed in multi-zone environments with network traffic often relying on obscure endpoint matching and routing for a diff --git a/linkerd.io/content/2.16/tasks/enabling-topology-aware-hints.md b/linkerd.io/content/2.16/tasks/enabling-topology-aware-hints.md index f681823a38..ffd9c8a82a 100644 --- a/linkerd.io/content/2.16/tasks/enabling-topology-aware-hints.md +++ b/linkerd.io/content/2.16/tasks/enabling-topology-aware-hints.md @@ -1,7 +1,8 @@ -+++ -title = "Enabling Topology Aware Hints" -description = "Enable topology aware hints to allow Linkerd to intelligently choose same-zone endpoints" -+++ +--- +title: 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 diff --git a/linkerd.io/content/2.17/features/topology-aware-hints.md b/linkerd.io/content/2.17/features/topology-aware-hints.md index 4903e0e8d2..4878f692f1 100644 --- a/linkerd.io/content/2.17/features/topology-aware-hints.md +++ b/linkerd.io/content/2.17/features/topology-aware-hints.md @@ -1,10 +1,8 @@ -+++ -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/" -] -+++ +--- +title: Topology Aware Hints +description: |- + Linkerd's implementation of Kubernetes topology aware hints enables endpoint consumption based on a node's zone label. +--- Kubernetes clusters are increasingly deployed in multi-zone environments with network traffic often relying on obscure endpoint matching and routing for a diff --git a/linkerd.io/content/2.17/tasks/enabling-topology-aware-hints.md b/linkerd.io/content/2.17/tasks/enabling-topology-aware-hints.md index f681823a38..ffd9c8a82a 100644 --- a/linkerd.io/content/2.17/tasks/enabling-topology-aware-hints.md +++ b/linkerd.io/content/2.17/tasks/enabling-topology-aware-hints.md @@ -1,7 +1,8 @@ -+++ -title = "Enabling Topology Aware Hints" -description = "Enable topology aware hints to allow Linkerd to intelligently choose same-zone endpoints" -+++ +--- +title: 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 From c245621a735b796cde0e7746a8a2efefc352be55 Mon Sep 17 00:00:00 2001 From: Flynn Date: Mon, 3 Feb 2025 13:58:31 -0500 Subject: [PATCH 8/9] Fix "stable distribution" link Signed-off-by: Flynn --- linkerd.io/content/2.16/features/topology-aware-hints.md | 4 ++-- .../content/2.16/tasks/enabling-topology-aware-hints.md | 4 ++-- linkerd.io/content/2.17/features/topology-aware-hints.md | 4 ++-- .../content/2.17/tasks/enabling-topology-aware-hints.md | 4 ++-- 4 files changed, 8 insertions(+), 8 deletions(-) diff --git a/linkerd.io/content/2.16/features/topology-aware-hints.md b/linkerd.io/content/2.16/features/topology-aware-hints.md index 4878f692f1..1164d94564 100644 --- a/linkerd.io/content/2.16/features/topology-aware-hints.md +++ b/linkerd.io/content/2.16/features/topology-aware-hints.md @@ -24,8 +24,8 @@ zone. {{< note >}} -If you're using a [stable distribution](/releases/#stable) of Linkerd, it may -have additional features related to topology-aware routing (for example, Buoyant Enterprise for Linkerd and its HAZL diff --git a/linkerd.io/content/2.16/tasks/enabling-topology-aware-hints.md b/linkerd.io/content/2.16/tasks/enabling-topology-aware-hints.md index ffd9c8a82a..40a0eae6e2 100644 --- a/linkerd.io/content/2.16/tasks/enabling-topology-aware-hints.md +++ b/linkerd.io/content/2.16/tasks/enabling-topology-aware-hints.md @@ -11,8 +11,8 @@ the associated costs and latency. {{< note >}} -If you're using a [stable distribution](/releases/#stable) of Linkerd, it may -have additional features related to topology-aware routing (for example, Buoyant Enterprise for Linkerd and its HAZL diff --git a/linkerd.io/content/2.17/features/topology-aware-hints.md b/linkerd.io/content/2.17/features/topology-aware-hints.md index 4878f692f1..1164d94564 100644 --- a/linkerd.io/content/2.17/features/topology-aware-hints.md +++ b/linkerd.io/content/2.17/features/topology-aware-hints.md @@ -24,8 +24,8 @@ zone. {{< note >}} -If you're using a [stable distribution](/releases/#stable) of Linkerd, it may -have additional features related to topology-aware routing (for example, Buoyant Enterprise for Linkerd and its HAZL diff --git a/linkerd.io/content/2.17/tasks/enabling-topology-aware-hints.md b/linkerd.io/content/2.17/tasks/enabling-topology-aware-hints.md index ffd9c8a82a..40a0eae6e2 100644 --- a/linkerd.io/content/2.17/tasks/enabling-topology-aware-hints.md +++ b/linkerd.io/content/2.17/tasks/enabling-topology-aware-hints.md @@ -11,8 +11,8 @@ the associated costs and latency. {{< note >}} -If you're using a [stable distribution](/releases/#stable) of Linkerd, it may -have additional features related to topology-aware routing (for example, Buoyant Enterprise for Linkerd and its HAZL From 83fec681218daa6f4afae735b9ae38168b8d9db3 Mon Sep 17 00:00:00 2001 From: Flynn Date: Fri, 7 Feb 2025 21:09:40 -0500 Subject: [PATCH 9/9] Hints -> Routing, vet for correctness, and note that we don't do the new trafficDistribution feature Signed-off-by: Flynn --- .../2.12/features/topology-aware-hints.md | 36 ----------- .../2.12/features/topology-aware-routing.md | 47 +++++++++++++++ .../tasks/enabling-topology-aware-routing.md} | 52 +++++++++------- .../2.13/features/topology-aware-hints.md | 36 ----------- .../2.13/features/topology-aware-routing.md | 47 +++++++++++++++ .../tasks/enabling-topology-aware-routing.md} | 52 +++++++++------- .../2.14/features/topology-aware-hints.md | 36 ----------- .../2.14/features/topology-aware-routing.md | 47 +++++++++++++++ .../tasks/enabling-topology-aware-routing.md} | 52 +++++++++------- .../2.15/features/topology-aware-hints.md | 36 ----------- .../2.15/features/topology-aware-routing.md | 47 +++++++++++++++ .../tasks/enabling-topology-aware-routing.md} | 52 +++++++++------- .../2.16/features/topology-aware-hints.md | 48 --------------- .../2.16/features/topology-aware-routing.md | 59 +++++++++++++++++++ ....md => enabling-topology-aware-routing.md} | 52 +++++++++------- .../2.17/features/topology-aware-hints.md | 48 --------------- .../2.17/features/topology-aware-routing.md | 59 +++++++++++++++++++ ....md => enabling-topology-aware-routing.md} | 52 +++++++++------- 18 files changed, 492 insertions(+), 366 deletions(-) delete mode 100644 linkerd.io/content/2.12/features/topology-aware-hints.md create mode 100644 linkerd.io/content/2.12/features/topology-aware-routing.md rename linkerd.io/content/{2.14/tasks/enabling-topology-aware-hints.md => 2.12/tasks/enabling-topology-aware-routing.md} (54%) delete mode 100644 linkerd.io/content/2.13/features/topology-aware-hints.md create mode 100644 linkerd.io/content/2.13/features/topology-aware-routing.md rename linkerd.io/content/{2.12/tasks/enabling-topology-aware-hints.md => 2.13/tasks/enabling-topology-aware-routing.md} (54%) delete mode 100644 linkerd.io/content/2.14/features/topology-aware-hints.md create mode 100644 linkerd.io/content/2.14/features/topology-aware-routing.md rename linkerd.io/content/{2.15/tasks/enabling-topology-aware-hints.md => 2.14/tasks/enabling-topology-aware-routing.md} (54%) delete mode 100644 linkerd.io/content/2.15/features/topology-aware-hints.md create mode 100644 linkerd.io/content/2.15/features/topology-aware-routing.md rename linkerd.io/content/{2.13/tasks/enabling-topology-aware-hints.md => 2.15/tasks/enabling-topology-aware-routing.md} (54%) delete mode 100644 linkerd.io/content/2.16/features/topology-aware-hints.md create mode 100644 linkerd.io/content/2.16/features/topology-aware-routing.md rename linkerd.io/content/2.16/tasks/{enabling-topology-aware-hints.md => enabling-topology-aware-routing.md} (59%) delete mode 100644 linkerd.io/content/2.17/features/topology-aware-hints.md create mode 100644 linkerd.io/content/2.17/features/topology-aware-routing.md rename linkerd.io/content/2.17/tasks/{enabling-topology-aware-hints.md => enabling-topology-aware-routing.md} (59%) diff --git a/linkerd.io/content/2.12/features/topology-aware-hints.md b/linkerd.io/content/2.12/features/topology-aware-hints.md deleted file mode 100644 index 2cd2eb1a14..0000000000 --- a/linkerd.io/content/2.12/features/topology-aware-hints.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: Topology Aware Hints -description: |- - Linkerd's implementation of Kubernetes topology aware hints enables endpoint consumption based on a node's zone label. ---- - -Kubernetes clusters are increasingly deployed in multi-zone environments with -network traffic often relying on obscure 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 cluster that spans -multiple zones. 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. - -The goal of topology aware hints is to to provide a simpler way for users to -prefer endpoints by basing decisions solely off the node's -`topology.kubernetes.io/zone` label. If a client is in `zone-a`, then it -should prefer endpoints marked for use by clients in `zone-a`. When the -feature is enabled and the label set, Linkerd's destination controller will -attempt to find endpoints whose `Hints.ForZones` field matches the client's -zone. - -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/ - -{{< note >}} - -Topology aware hints require that the cluster have the `TopologyAwareHints` -feature gate enabled, and that Linkerd's `endpointSlice` feature be turned on -(this is the default starting with Linkerd stable-2.12). - -{{< /note >}} diff --git a/linkerd.io/content/2.12/features/topology-aware-routing.md b/linkerd.io/content/2.12/features/topology-aware-routing.md new file mode 100644 index 0000000000..245c39100d --- /dev/null +++ b/linkerd.io/content/2.12/features/topology-aware-routing.md @@ -0,0 +1,47 @@ +--- +title: Topology Aware Routing +description: |- + Linkerd's implementation of Kubernetes topology aware routing enables endpoint consumption based on a node's zone label. +--- + +Kubernetes clusters are increasingly deployed in multi-zone environments with +network traffic often relying on obscure endpoint matching and routing for a +given service. Linkerd's implementation of Kubernetes ([Topology Aware +Routing][topology aware routing]) provides users with a mechanism for +asserting more control over endpoint selection and routing within a cluster +that spans multiple zones. 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. + +The goal of topology aware routing is to to provide a simpler way for users to +prefer endpoints by basing decisions solely off the node's +`topology.kubernetes.io/zone` label. If a client is in `zone-a`, then it +should prefer endpoints marked for use by clients in `zone-a`. When the +feature is enabled and the label set, Linkerd's destination controller will +attempt to find endpoints whose `routing.ForZones` field matches the client's +zone. + +To get started with topology aware routing take a look at the [enabling +topology aware routing](../../tasks/enabling-topology-aware-routing/) task +documentation. + +[topology aware routing]: + https://kubernetes.io/docs/concepts/services-networking/topology-aware-routing/ + +{{< note >}} + +Topology aware routing requires that the cluster have the `TopologyAwareHints` +feature gate enabled (which is the default starting with Kubernetes 1.24), and +that Linkerd's `endpointSlice` feature be turned on (this is the default +starting with Linkerd stable-2.12). + +{{< /note >}} + +{{< note >}} + +Starting in Kubernetes 1.31, Kubernetes also has the `trafficDistribution` +feature available as an alternative to topology aware routing. +`trafficDistribution` is not yet supported by Linkerd. + +{{< /note >}} diff --git a/linkerd.io/content/2.14/tasks/enabling-topology-aware-hints.md b/linkerd.io/content/2.12/tasks/enabling-topology-aware-routing.md similarity index 54% rename from linkerd.io/content/2.14/tasks/enabling-topology-aware-hints.md rename to linkerd.io/content/2.12/tasks/enabling-topology-aware-routing.md index cbbd82e50e..fd5f8d5f0b 100644 --- a/linkerd.io/content/2.14/tasks/enabling-topology-aware-hints.md +++ b/linkerd.io/content/2.12/tasks/enabling-topology-aware-routing.md @@ -1,20 +1,24 @@ --- -title: "Enabling Topology Aware Hints" +title: "Enabling Topology Aware Routing" description: |- - Enable topology aware hints to allow Linkerd to intelligently choose same-zone endpoints + Enable topology aware routing 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. +[Topology aware routing](../../features/topology-aware-routing/) allows +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: +There are three requirements to successfully enabling topology aware routing +with Linkerd: -1. `TopologyAwareHints` feature gate MUST be enabled on the Kubernetes - cluster. -2. Each Kubernetes node should be labeled with the +1. The `TopologyAwareHints` feature gate MUST be enabled on the Kubernetes + cluster. (This feature gate is enabled by default in Kubernetes 1.24 and + later.) + +2. Each Kubernetes node needs to be assigned to a zone, using `"topology.kubernetes.io/zone` label. + 3. Relevant Kubernetes services will need to be modified with the `service.kubernetes.io/topology-aware-hints=auto` annotation. @@ -22,7 +26,7 @@ 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 there are several -[safeguards][topology-aware-hints-safeguards] that Kubernetes checks before +[safeguards][topology-aware-routing-safeguards] that Kubernetes checks before setting it. 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. @@ -40,17 +44,23 @@ node the client is on and limits cross-node and cross-zone communication. ## Constraints -Kubernetes places some [constraints][topology-aware-hints-constraints] on -topology aware hints that you should review before enabling topology aware -hints on Linkerd. +Kubernetes places some [constraints][topology-aware-routing-constraints] on +topology aware routing that you should review before trying to enable topology +aware routing on Linkerd. The main things to be aware of are: -- Linkerd assumes that traffic to a given zone will be roughly proportional to - the capacity of the nodes in the zone (which can be a concern when using - horizontal pod autoscaling, as the HPA may start nodes in the "wrong" zone); - and -- The Kubernetes endpoint slice controller does not take... +- Topology aware routing assumes that traffic to a given zone will be roughly + proportional to the capacity of the nodes in the zone. This can be a concern + when using horizontal pod autoscaling, as HPA may start nodes in the "wrong" + zone. + +- Services with `internalTrafficPolicy` set to `Local` ignore topology aware + routing, by design. + +- If you have workloads running on Nodes labeled with `control-plane` or + `master` role, topology aware routing will not route to endpoints on these + Nodes. ## Configuring Topology Aware Routing @@ -63,5 +73,5 @@ time="2021-08-27T14:04:35Z" level=info msg="Establishing watch on endpoint [defa 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" ``` -[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 +[topology-aware-routing-safeguards]: https://kubernetes.io/docs/concepts/services-networking/topology-aware-hints/#safeguards +[topology-aware-routing-constraints]: https://kubernetes.io/docs/concepts/services-networking/topology-aware-hints/#constraints diff --git a/linkerd.io/content/2.13/features/topology-aware-hints.md b/linkerd.io/content/2.13/features/topology-aware-hints.md deleted file mode 100644 index 2cd2eb1a14..0000000000 --- a/linkerd.io/content/2.13/features/topology-aware-hints.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: Topology Aware Hints -description: |- - Linkerd's implementation of Kubernetes topology aware hints enables endpoint consumption based on a node's zone label. ---- - -Kubernetes clusters are increasingly deployed in multi-zone environments with -network traffic often relying on obscure 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 cluster that spans -multiple zones. 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. - -The goal of topology aware hints is to to provide a simpler way for users to -prefer endpoints by basing decisions solely off the node's -`topology.kubernetes.io/zone` label. If a client is in `zone-a`, then it -should prefer endpoints marked for use by clients in `zone-a`. When the -feature is enabled and the label set, Linkerd's destination controller will -attempt to find endpoints whose `Hints.ForZones` field matches the client's -zone. - -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/ - -{{< note >}} - -Topology aware hints require that the cluster have the `TopologyAwareHints` -feature gate enabled, and that Linkerd's `endpointSlice` feature be turned on -(this is the default starting with Linkerd stable-2.12). - -{{< /note >}} diff --git a/linkerd.io/content/2.13/features/topology-aware-routing.md b/linkerd.io/content/2.13/features/topology-aware-routing.md new file mode 100644 index 0000000000..245c39100d --- /dev/null +++ b/linkerd.io/content/2.13/features/topology-aware-routing.md @@ -0,0 +1,47 @@ +--- +title: Topology Aware Routing +description: |- + Linkerd's implementation of Kubernetes topology aware routing enables endpoint consumption based on a node's zone label. +--- + +Kubernetes clusters are increasingly deployed in multi-zone environments with +network traffic often relying on obscure endpoint matching and routing for a +given service. Linkerd's implementation of Kubernetes ([Topology Aware +Routing][topology aware routing]) provides users with a mechanism for +asserting more control over endpoint selection and routing within a cluster +that spans multiple zones. 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. + +The goal of topology aware routing is to to provide a simpler way for users to +prefer endpoints by basing decisions solely off the node's +`topology.kubernetes.io/zone` label. If a client is in `zone-a`, then it +should prefer endpoints marked for use by clients in `zone-a`. When the +feature is enabled and the label set, Linkerd's destination controller will +attempt to find endpoints whose `routing.ForZones` field matches the client's +zone. + +To get started with topology aware routing take a look at the [enabling +topology aware routing](../../tasks/enabling-topology-aware-routing/) task +documentation. + +[topology aware routing]: + https://kubernetes.io/docs/concepts/services-networking/topology-aware-routing/ + +{{< note >}} + +Topology aware routing requires that the cluster have the `TopologyAwareHints` +feature gate enabled (which is the default starting with Kubernetes 1.24), and +that Linkerd's `endpointSlice` feature be turned on (this is the default +starting with Linkerd stable-2.12). + +{{< /note >}} + +{{< note >}} + +Starting in Kubernetes 1.31, Kubernetes also has the `trafficDistribution` +feature available as an alternative to topology aware routing. +`trafficDistribution` is not yet supported by Linkerd. + +{{< /note >}} diff --git a/linkerd.io/content/2.12/tasks/enabling-topology-aware-hints.md b/linkerd.io/content/2.13/tasks/enabling-topology-aware-routing.md similarity index 54% rename from linkerd.io/content/2.12/tasks/enabling-topology-aware-hints.md rename to linkerd.io/content/2.13/tasks/enabling-topology-aware-routing.md index cbbd82e50e..fd5f8d5f0b 100644 --- a/linkerd.io/content/2.12/tasks/enabling-topology-aware-hints.md +++ b/linkerd.io/content/2.13/tasks/enabling-topology-aware-routing.md @@ -1,20 +1,24 @@ --- -title: "Enabling Topology Aware Hints" +title: "Enabling Topology Aware Routing" description: |- - Enable topology aware hints to allow Linkerd to intelligently choose same-zone endpoints + Enable topology aware routing 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. +[Topology aware routing](../../features/topology-aware-routing/) allows +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: +There are three requirements to successfully enabling topology aware routing +with Linkerd: -1. `TopologyAwareHints` feature gate MUST be enabled on the Kubernetes - cluster. -2. Each Kubernetes node should be labeled with the +1. The `TopologyAwareHints` feature gate MUST be enabled on the Kubernetes + cluster. (This feature gate is enabled by default in Kubernetes 1.24 and + later.) + +2. Each Kubernetes node needs to be assigned to a zone, using `"topology.kubernetes.io/zone` label. + 3. Relevant Kubernetes services will need to be modified with the `service.kubernetes.io/topology-aware-hints=auto` annotation. @@ -22,7 +26,7 @@ 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 there are several -[safeguards][topology-aware-hints-safeguards] that Kubernetes checks before +[safeguards][topology-aware-routing-safeguards] that Kubernetes checks before setting it. 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. @@ -40,17 +44,23 @@ node the client is on and limits cross-node and cross-zone communication. ## Constraints -Kubernetes places some [constraints][topology-aware-hints-constraints] on -topology aware hints that you should review before enabling topology aware -hints on Linkerd. +Kubernetes places some [constraints][topology-aware-routing-constraints] on +topology aware routing that you should review before trying to enable topology +aware routing on Linkerd. The main things to be aware of are: -- Linkerd assumes that traffic to a given zone will be roughly proportional to - the capacity of the nodes in the zone (which can be a concern when using - horizontal pod autoscaling, as the HPA may start nodes in the "wrong" zone); - and -- The Kubernetes endpoint slice controller does not take... +- Topology aware routing assumes that traffic to a given zone will be roughly + proportional to the capacity of the nodes in the zone. This can be a concern + when using horizontal pod autoscaling, as HPA may start nodes in the "wrong" + zone. + +- Services with `internalTrafficPolicy` set to `Local` ignore topology aware + routing, by design. + +- If you have workloads running on Nodes labeled with `control-plane` or + `master` role, topology aware routing will not route to endpoints on these + Nodes. ## Configuring Topology Aware Routing @@ -63,5 +73,5 @@ time="2021-08-27T14:04:35Z" level=info msg="Establishing watch on endpoint [defa 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" ``` -[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 +[topology-aware-routing-safeguards]: https://kubernetes.io/docs/concepts/services-networking/topology-aware-hints/#safeguards +[topology-aware-routing-constraints]: https://kubernetes.io/docs/concepts/services-networking/topology-aware-hints/#constraints diff --git a/linkerd.io/content/2.14/features/topology-aware-hints.md b/linkerd.io/content/2.14/features/topology-aware-hints.md deleted file mode 100644 index 2cd2eb1a14..0000000000 --- a/linkerd.io/content/2.14/features/topology-aware-hints.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: Topology Aware Hints -description: |- - Linkerd's implementation of Kubernetes topology aware hints enables endpoint consumption based on a node's zone label. ---- - -Kubernetes clusters are increasingly deployed in multi-zone environments with -network traffic often relying on obscure 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 cluster that spans -multiple zones. 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. - -The goal of topology aware hints is to to provide a simpler way for users to -prefer endpoints by basing decisions solely off the node's -`topology.kubernetes.io/zone` label. If a client is in `zone-a`, then it -should prefer endpoints marked for use by clients in `zone-a`. When the -feature is enabled and the label set, Linkerd's destination controller will -attempt to find endpoints whose `Hints.ForZones` field matches the client's -zone. - -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/ - -{{< note >}} - -Topology aware hints require that the cluster have the `TopologyAwareHints` -feature gate enabled, and that Linkerd's `endpointSlice` feature be turned on -(this is the default starting with Linkerd stable-2.12). - -{{< /note >}} diff --git a/linkerd.io/content/2.14/features/topology-aware-routing.md b/linkerd.io/content/2.14/features/topology-aware-routing.md new file mode 100644 index 0000000000..245c39100d --- /dev/null +++ b/linkerd.io/content/2.14/features/topology-aware-routing.md @@ -0,0 +1,47 @@ +--- +title: Topology Aware Routing +description: |- + Linkerd's implementation of Kubernetes topology aware routing enables endpoint consumption based on a node's zone label. +--- + +Kubernetes clusters are increasingly deployed in multi-zone environments with +network traffic often relying on obscure endpoint matching and routing for a +given service. Linkerd's implementation of Kubernetes ([Topology Aware +Routing][topology aware routing]) provides users with a mechanism for +asserting more control over endpoint selection and routing within a cluster +that spans multiple zones. 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. + +The goal of topology aware routing is to to provide a simpler way for users to +prefer endpoints by basing decisions solely off the node's +`topology.kubernetes.io/zone` label. If a client is in `zone-a`, then it +should prefer endpoints marked for use by clients in `zone-a`. When the +feature is enabled and the label set, Linkerd's destination controller will +attempt to find endpoints whose `routing.ForZones` field matches the client's +zone. + +To get started with topology aware routing take a look at the [enabling +topology aware routing](../../tasks/enabling-topology-aware-routing/) task +documentation. + +[topology aware routing]: + https://kubernetes.io/docs/concepts/services-networking/topology-aware-routing/ + +{{< note >}} + +Topology aware routing requires that the cluster have the `TopologyAwareHints` +feature gate enabled (which is the default starting with Kubernetes 1.24), and +that Linkerd's `endpointSlice` feature be turned on (this is the default +starting with Linkerd stable-2.12). + +{{< /note >}} + +{{< note >}} + +Starting in Kubernetes 1.31, Kubernetes also has the `trafficDistribution` +feature available as an alternative to topology aware routing. +`trafficDistribution` is not yet supported by Linkerd. + +{{< /note >}} diff --git a/linkerd.io/content/2.15/tasks/enabling-topology-aware-hints.md b/linkerd.io/content/2.14/tasks/enabling-topology-aware-routing.md similarity index 54% rename from linkerd.io/content/2.15/tasks/enabling-topology-aware-hints.md rename to linkerd.io/content/2.14/tasks/enabling-topology-aware-routing.md index cbbd82e50e..fd5f8d5f0b 100644 --- a/linkerd.io/content/2.15/tasks/enabling-topology-aware-hints.md +++ b/linkerd.io/content/2.14/tasks/enabling-topology-aware-routing.md @@ -1,20 +1,24 @@ --- -title: "Enabling Topology Aware Hints" +title: "Enabling Topology Aware Routing" description: |- - Enable topology aware hints to allow Linkerd to intelligently choose same-zone endpoints + Enable topology aware routing 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. +[Topology aware routing](../../features/topology-aware-routing/) allows +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: +There are three requirements to successfully enabling topology aware routing +with Linkerd: -1. `TopologyAwareHints` feature gate MUST be enabled on the Kubernetes - cluster. -2. Each Kubernetes node should be labeled with the +1. The `TopologyAwareHints` feature gate MUST be enabled on the Kubernetes + cluster. (This feature gate is enabled by default in Kubernetes 1.24 and + later.) + +2. Each Kubernetes node needs to be assigned to a zone, using `"topology.kubernetes.io/zone` label. + 3. Relevant Kubernetes services will need to be modified with the `service.kubernetes.io/topology-aware-hints=auto` annotation. @@ -22,7 +26,7 @@ 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 there are several -[safeguards][topology-aware-hints-safeguards] that Kubernetes checks before +[safeguards][topology-aware-routing-safeguards] that Kubernetes checks before setting it. 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. @@ -40,17 +44,23 @@ node the client is on and limits cross-node and cross-zone communication. ## Constraints -Kubernetes places some [constraints][topology-aware-hints-constraints] on -topology aware hints that you should review before enabling topology aware -hints on Linkerd. +Kubernetes places some [constraints][topology-aware-routing-constraints] on +topology aware routing that you should review before trying to enable topology +aware routing on Linkerd. The main things to be aware of are: -- Linkerd assumes that traffic to a given zone will be roughly proportional to - the capacity of the nodes in the zone (which can be a concern when using - horizontal pod autoscaling, as the HPA may start nodes in the "wrong" zone); - and -- The Kubernetes endpoint slice controller does not take... +- Topology aware routing assumes that traffic to a given zone will be roughly + proportional to the capacity of the nodes in the zone. This can be a concern + when using horizontal pod autoscaling, as HPA may start nodes in the "wrong" + zone. + +- Services with `internalTrafficPolicy` set to `Local` ignore topology aware + routing, by design. + +- If you have workloads running on Nodes labeled with `control-plane` or + `master` role, topology aware routing will not route to endpoints on these + Nodes. ## Configuring Topology Aware Routing @@ -63,5 +73,5 @@ time="2021-08-27T14:04:35Z" level=info msg="Establishing watch on endpoint [defa 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" ``` -[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 +[topology-aware-routing-safeguards]: https://kubernetes.io/docs/concepts/services-networking/topology-aware-hints/#safeguards +[topology-aware-routing-constraints]: https://kubernetes.io/docs/concepts/services-networking/topology-aware-hints/#constraints diff --git a/linkerd.io/content/2.15/features/topology-aware-hints.md b/linkerd.io/content/2.15/features/topology-aware-hints.md deleted file mode 100644 index 2cd2eb1a14..0000000000 --- a/linkerd.io/content/2.15/features/topology-aware-hints.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: Topology Aware Hints -description: |- - Linkerd's implementation of Kubernetes topology aware hints enables endpoint consumption based on a node's zone label. ---- - -Kubernetes clusters are increasingly deployed in multi-zone environments with -network traffic often relying on obscure 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 cluster that spans -multiple zones. 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. - -The goal of topology aware hints is to to provide a simpler way for users to -prefer endpoints by basing decisions solely off the node's -`topology.kubernetes.io/zone` label. If a client is in `zone-a`, then it -should prefer endpoints marked for use by clients in `zone-a`. When the -feature is enabled and the label set, Linkerd's destination controller will -attempt to find endpoints whose `Hints.ForZones` field matches the client's -zone. - -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/ - -{{< note >}} - -Topology aware hints require that the cluster have the `TopologyAwareHints` -feature gate enabled, and that Linkerd's `endpointSlice` feature be turned on -(this is the default starting with Linkerd stable-2.12). - -{{< /note >}} diff --git a/linkerd.io/content/2.15/features/topology-aware-routing.md b/linkerd.io/content/2.15/features/topology-aware-routing.md new file mode 100644 index 0000000000..245c39100d --- /dev/null +++ b/linkerd.io/content/2.15/features/topology-aware-routing.md @@ -0,0 +1,47 @@ +--- +title: Topology Aware Routing +description: |- + Linkerd's implementation of Kubernetes topology aware routing enables endpoint consumption based on a node's zone label. +--- + +Kubernetes clusters are increasingly deployed in multi-zone environments with +network traffic often relying on obscure endpoint matching and routing for a +given service. Linkerd's implementation of Kubernetes ([Topology Aware +Routing][topology aware routing]) provides users with a mechanism for +asserting more control over endpoint selection and routing within a cluster +that spans multiple zones. 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. + +The goal of topology aware routing is to to provide a simpler way for users to +prefer endpoints by basing decisions solely off the node's +`topology.kubernetes.io/zone` label. If a client is in `zone-a`, then it +should prefer endpoints marked for use by clients in `zone-a`. When the +feature is enabled and the label set, Linkerd's destination controller will +attempt to find endpoints whose `routing.ForZones` field matches the client's +zone. + +To get started with topology aware routing take a look at the [enabling +topology aware routing](../../tasks/enabling-topology-aware-routing/) task +documentation. + +[topology aware routing]: + https://kubernetes.io/docs/concepts/services-networking/topology-aware-routing/ + +{{< note >}} + +Topology aware routing requires that the cluster have the `TopologyAwareHints` +feature gate enabled (which is the default starting with Kubernetes 1.24), and +that Linkerd's `endpointSlice` feature be turned on (this is the default +starting with Linkerd stable-2.12). + +{{< /note >}} + +{{< note >}} + +Starting in Kubernetes 1.31, Kubernetes also has the `trafficDistribution` +feature available as an alternative to topology aware routing. +`trafficDistribution` is not yet supported by Linkerd. + +{{< /note >}} diff --git a/linkerd.io/content/2.13/tasks/enabling-topology-aware-hints.md b/linkerd.io/content/2.15/tasks/enabling-topology-aware-routing.md similarity index 54% rename from linkerd.io/content/2.13/tasks/enabling-topology-aware-hints.md rename to linkerd.io/content/2.15/tasks/enabling-topology-aware-routing.md index cbbd82e50e..fd5f8d5f0b 100644 --- a/linkerd.io/content/2.13/tasks/enabling-topology-aware-hints.md +++ b/linkerd.io/content/2.15/tasks/enabling-topology-aware-routing.md @@ -1,20 +1,24 @@ --- -title: "Enabling Topology Aware Hints" +title: "Enabling Topology Aware Routing" description: |- - Enable topology aware hints to allow Linkerd to intelligently choose same-zone endpoints + Enable topology aware routing 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. +[Topology aware routing](../../features/topology-aware-routing/) allows +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: +There are three requirements to successfully enabling topology aware routing +with Linkerd: -1. `TopologyAwareHints` feature gate MUST be enabled on the Kubernetes - cluster. -2. Each Kubernetes node should be labeled with the +1. The `TopologyAwareHints` feature gate MUST be enabled on the Kubernetes + cluster. (This feature gate is enabled by default in Kubernetes 1.24 and + later.) + +2. Each Kubernetes node needs to be assigned to a zone, using `"topology.kubernetes.io/zone` label. + 3. Relevant Kubernetes services will need to be modified with the `service.kubernetes.io/topology-aware-hints=auto` annotation. @@ -22,7 +26,7 @@ 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 there are several -[safeguards][topology-aware-hints-safeguards] that Kubernetes checks before +[safeguards][topology-aware-routing-safeguards] that Kubernetes checks before setting it. 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. @@ -40,17 +44,23 @@ node the client is on and limits cross-node and cross-zone communication. ## Constraints -Kubernetes places some [constraints][topology-aware-hints-constraints] on -topology aware hints that you should review before enabling topology aware -hints on Linkerd. +Kubernetes places some [constraints][topology-aware-routing-constraints] on +topology aware routing that you should review before trying to enable topology +aware routing on Linkerd. The main things to be aware of are: -- Linkerd assumes that traffic to a given zone will be roughly proportional to - the capacity of the nodes in the zone (which can be a concern when using - horizontal pod autoscaling, as the HPA may start nodes in the "wrong" zone); - and -- The Kubernetes endpoint slice controller does not take... +- Topology aware routing assumes that traffic to a given zone will be roughly + proportional to the capacity of the nodes in the zone. This can be a concern + when using horizontal pod autoscaling, as HPA may start nodes in the "wrong" + zone. + +- Services with `internalTrafficPolicy` set to `Local` ignore topology aware + routing, by design. + +- If you have workloads running on Nodes labeled with `control-plane` or + `master` role, topology aware routing will not route to endpoints on these + Nodes. ## Configuring Topology Aware Routing @@ -63,5 +73,5 @@ time="2021-08-27T14:04:35Z" level=info msg="Establishing watch on endpoint [defa 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" ``` -[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 +[topology-aware-routing-safeguards]: https://kubernetes.io/docs/concepts/services-networking/topology-aware-hints/#safeguards +[topology-aware-routing-constraints]: https://kubernetes.io/docs/concepts/services-networking/topology-aware-hints/#constraints diff --git a/linkerd.io/content/2.16/features/topology-aware-hints.md b/linkerd.io/content/2.16/features/topology-aware-hints.md deleted file mode 100644 index 1164d94564..0000000000 --- a/linkerd.io/content/2.16/features/topology-aware-hints.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: Topology Aware Hints -description: |- - Linkerd's implementation of Kubernetes topology aware hints enables endpoint consumption based on a node's zone label. ---- - -Kubernetes clusters are increasingly deployed in multi-zone environments with -network traffic often relying on obscure 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 cluster that spans -multiple zones. 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. - -The goal of topology aware hints is to to provide a simpler way for users to -prefer endpoints by basing decisions solely off the node's -`topology.kubernetes.io/zone` label. If a client is in `zone-a`, then it -should prefer endpoints marked for use by clients in `zone-a`. When the -feature is enabled and the label set, Linkerd's destination controller will -attempt to find endpoints whose `Hints.ForZones` field matches the client's -zone. - -{{< note >}} - -If you're using a [stable distribution](/releases/) of Linkerd, it may have -additional features related to topology-aware routing (for example, Buoyant Enterprise for -Linkerd and its HAZL -feature). You can find more information about the different kinds of Linkerd -releases on the [Releases and Versions](/releases/) page. - -{{< /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/ - -{{< note >}} - -Topology aware hints require that the cluster have the `TopologyAwareHints` -feature gate enabled, and that Linkerd's `endpointSlice` feature be turned on -(this is the default starting with Linkerd stable-2.12). - -{{< /note >}} diff --git a/linkerd.io/content/2.16/features/topology-aware-routing.md b/linkerd.io/content/2.16/features/topology-aware-routing.md new file mode 100644 index 0000000000..3d826eaaac --- /dev/null +++ b/linkerd.io/content/2.16/features/topology-aware-routing.md @@ -0,0 +1,59 @@ +--- +title: Topology Aware Routing +description: |- + Linkerd's implementation of Kubernetes topology aware routing enables endpoint consumption based on a node's zone label. +--- + +Kubernetes clusters are increasingly deployed in multi-zone environments with +network traffic often relying on obscure endpoint matching and routing for a +given service. Linkerd's implementation of Kubernetes ([Topology Aware +Routing][topology aware routing]) provides users with a mechanism for +asserting more control over endpoint selection and routing within a cluster +that spans multiple zones. 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. + +The goal of topology aware routing is to to provide a simpler way for users to +prefer endpoints by basing decisions solely off the node's +`topology.kubernetes.io/zone` label. If a client is in `zone-a`, then it +should prefer endpoints marked for use by clients in `zone-a`. When the +feature is enabled and the label set, Linkerd's destination controller will +attempt to find endpoints whose `routing.ForZones` field matches the client's +zone. + +{{< note >}} + +If you're using a [stable distribution](/releases/) of Linkerd, it may have +additional features related to topology-aware routing (for example, Buoyant Enterprise for +Linkerd and its HAZL +feature). You can find more information about the different kinds of Linkerd +releases on the [Releases and Versions](/releases/) page. + +{{< /note >}} + +To get started with topology aware routing take a look at the [enabling +topology aware routing](../../tasks/enabling-topology-aware-routing/) task +documentation. + +[topology aware routing]: + https://kubernetes.io/docs/concepts/services-networking/topology-aware-routing/ + +{{< note >}} + +Topology aware routing requires that the cluster have the `TopologyAwareHints` +feature gate enabled (which is the default starting with Kubernetes 1.24), and +that Linkerd's `endpointSlice` feature be turned on (this is the default +starting with Linkerd stable-2.12). + +{{< /note >}} + +{{< note >}} + +Starting in Kubernetes 1.31, Kubernetes also has the `trafficDistribution` +feature available as an alternative to topology aware routing. +`trafficDistribution` is not yet supported by Linkerd. + +{{< /note >}} diff --git a/linkerd.io/content/2.16/tasks/enabling-topology-aware-hints.md b/linkerd.io/content/2.16/tasks/enabling-topology-aware-routing.md similarity index 59% rename from linkerd.io/content/2.16/tasks/enabling-topology-aware-hints.md rename to linkerd.io/content/2.16/tasks/enabling-topology-aware-routing.md index 40a0eae6e2..0d1b786d40 100644 --- a/linkerd.io/content/2.16/tasks/enabling-topology-aware-hints.md +++ b/linkerd.io/content/2.16/tasks/enabling-topology-aware-routing.md @@ -1,13 +1,13 @@ --- -title: Topology Aware Hints +title: "Enabling Topology Aware Routing" description: |- - Enable topology aware hints to allow Linkerd to intelligently choose same-zone endpoints + Enable topology aware routing 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. +[Topology aware routing](../../features/topology-aware-routing/) allows +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. {{< note >}} @@ -21,12 +21,16 @@ releases on the [Releases and Versions](/releases/) page. {{< /note >}} -There are three requirements to successfully enabling topology aware hints with Linkerd: +There are three requirements to successfully enabling topology aware routing +with Linkerd: -1. `TopologyAwareHints` feature gate MUST be enabled on the Kubernetes - cluster. -2. Each Kubernetes node should be labeled with the +1. The `TopologyAwareHints` feature gate MUST be enabled on the Kubernetes + cluster. (This feature gate is enabled by default in Kubernetes 1.24 and + later.) + +2. Each Kubernetes node needs to be assigned to a zone, using `"topology.kubernetes.io/zone` label. + 3. Relevant Kubernetes services will need to be modified with the `service.kubernetes.io/topology-aware-hints=auto` annotation. @@ -34,7 +38,7 @@ 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 there are several -[safeguards][topology-aware-hints-safeguards] that Kubernetes checks before +[safeguards][topology-aware-routing-safeguards] that Kubernetes checks before setting it. 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. @@ -52,17 +56,23 @@ node the client is on and limits cross-node and cross-zone communication. ## Constraints -Kubernetes places some [constraints][topology-aware-hints-constraints] on -topology aware hints that you should review before enabling topology aware -hints on Linkerd. +Kubernetes places some [constraints][topology-aware-routing-constraints] on +topology aware routing that you should review before trying to enable topology +aware routing on Linkerd. The main things to be aware of are: -- Linkerd assumes that traffic to a given zone will be roughly proportional to - the capacity of the nodes in the zone (which can be a concern when using - horizontal pod autoscaling, as the HPA may start nodes in the "wrong" zone); - and -- The Kubernetes endpoint slice controller does not take... +- Topology aware routing assumes that traffic to a given zone will be roughly + proportional to the capacity of the nodes in the zone. This can be a concern + when using horizontal pod autoscaling, as HPA may start nodes in the "wrong" + zone. + +- Services with `internalTrafficPolicy` set to `Local` ignore topology aware + routing, by design. + +- If you have workloads running on Nodes labeled with `control-plane` or + `master` role, topology aware routing will not route to endpoints on these + Nodes. ## Configuring Topology Aware Routing @@ -75,5 +85,5 @@ time="2021-08-27T14:04:35Z" level=info msg="Establishing watch on endpoint [defa 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" ``` -[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 +[topology-aware-routing-safeguards]: https://kubernetes.io/docs/concepts/services-networking/topology-aware-hints/#safeguards +[topology-aware-routing-constraints]: https://kubernetes.io/docs/concepts/services-networking/topology-aware-hints/#constraints diff --git a/linkerd.io/content/2.17/features/topology-aware-hints.md b/linkerd.io/content/2.17/features/topology-aware-hints.md deleted file mode 100644 index 1164d94564..0000000000 --- a/linkerd.io/content/2.17/features/topology-aware-hints.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: Topology Aware Hints -description: |- - Linkerd's implementation of Kubernetes topology aware hints enables endpoint consumption based on a node's zone label. ---- - -Kubernetes clusters are increasingly deployed in multi-zone environments with -network traffic often relying on obscure 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 cluster that spans -multiple zones. 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. - -The goal of topology aware hints is to to provide a simpler way for users to -prefer endpoints by basing decisions solely off the node's -`topology.kubernetes.io/zone` label. If a client is in `zone-a`, then it -should prefer endpoints marked for use by clients in `zone-a`. When the -feature is enabled and the label set, Linkerd's destination controller will -attempt to find endpoints whose `Hints.ForZones` field matches the client's -zone. - -{{< note >}} - -If you're using a [stable distribution](/releases/) of Linkerd, it may have -additional features related to topology-aware routing (for example, Buoyant Enterprise for -Linkerd and its HAZL -feature). You can find more information about the different kinds of Linkerd -releases on the [Releases and Versions](/releases/) page. - -{{< /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/ - -{{< note >}} - -Topology aware hints require that the cluster have the `TopologyAwareHints` -feature gate enabled, and that Linkerd's `endpointSlice` feature be turned on -(this is the default starting with Linkerd stable-2.12). - -{{< /note >}} diff --git a/linkerd.io/content/2.17/features/topology-aware-routing.md b/linkerd.io/content/2.17/features/topology-aware-routing.md new file mode 100644 index 0000000000..3d826eaaac --- /dev/null +++ b/linkerd.io/content/2.17/features/topology-aware-routing.md @@ -0,0 +1,59 @@ +--- +title: Topology Aware Routing +description: |- + Linkerd's implementation of Kubernetes topology aware routing enables endpoint consumption based on a node's zone label. +--- + +Kubernetes clusters are increasingly deployed in multi-zone environments with +network traffic often relying on obscure endpoint matching and routing for a +given service. Linkerd's implementation of Kubernetes ([Topology Aware +Routing][topology aware routing]) provides users with a mechanism for +asserting more control over endpoint selection and routing within a cluster +that spans multiple zones. 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. + +The goal of topology aware routing is to to provide a simpler way for users to +prefer endpoints by basing decisions solely off the node's +`topology.kubernetes.io/zone` label. If a client is in `zone-a`, then it +should prefer endpoints marked for use by clients in `zone-a`. When the +feature is enabled and the label set, Linkerd's destination controller will +attempt to find endpoints whose `routing.ForZones` field matches the client's +zone. + +{{< note >}} + +If you're using a [stable distribution](/releases/) of Linkerd, it may have +additional features related to topology-aware routing (for example, Buoyant Enterprise for +Linkerd and its HAZL +feature). You can find more information about the different kinds of Linkerd +releases on the [Releases and Versions](/releases/) page. + +{{< /note >}} + +To get started with topology aware routing take a look at the [enabling +topology aware routing](../../tasks/enabling-topology-aware-routing/) task +documentation. + +[topology aware routing]: + https://kubernetes.io/docs/concepts/services-networking/topology-aware-routing/ + +{{< note >}} + +Topology aware routing requires that the cluster have the `TopologyAwareHints` +feature gate enabled (which is the default starting with Kubernetes 1.24), and +that Linkerd's `endpointSlice` feature be turned on (this is the default +starting with Linkerd stable-2.12). + +{{< /note >}} + +{{< note >}} + +Starting in Kubernetes 1.31, Kubernetes also has the `trafficDistribution` +feature available as an alternative to topology aware routing. +`trafficDistribution` is not yet supported by Linkerd. + +{{< /note >}} diff --git a/linkerd.io/content/2.17/tasks/enabling-topology-aware-hints.md b/linkerd.io/content/2.17/tasks/enabling-topology-aware-routing.md similarity index 59% rename from linkerd.io/content/2.17/tasks/enabling-topology-aware-hints.md rename to linkerd.io/content/2.17/tasks/enabling-topology-aware-routing.md index 40a0eae6e2..0d1b786d40 100644 --- a/linkerd.io/content/2.17/tasks/enabling-topology-aware-hints.md +++ b/linkerd.io/content/2.17/tasks/enabling-topology-aware-routing.md @@ -1,13 +1,13 @@ --- -title: Topology Aware Hints +title: "Enabling Topology Aware Routing" description: |- - Enable topology aware hints to allow Linkerd to intelligently choose same-zone endpoints + Enable topology aware routing 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. +[Topology aware routing](../../features/topology-aware-routing/) allows +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. {{< note >}} @@ -21,12 +21,16 @@ releases on the [Releases and Versions](/releases/) page. {{< /note >}} -There are three requirements to successfully enabling topology aware hints with Linkerd: +There are three requirements to successfully enabling topology aware routing +with Linkerd: -1. `TopologyAwareHints` feature gate MUST be enabled on the Kubernetes - cluster. -2. Each Kubernetes node should be labeled with the +1. The `TopologyAwareHints` feature gate MUST be enabled on the Kubernetes + cluster. (This feature gate is enabled by default in Kubernetes 1.24 and + later.) + +2. Each Kubernetes node needs to be assigned to a zone, using `"topology.kubernetes.io/zone` label. + 3. Relevant Kubernetes services will need to be modified with the `service.kubernetes.io/topology-aware-hints=auto` annotation. @@ -34,7 +38,7 @@ 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 there are several -[safeguards][topology-aware-hints-safeguards] that Kubernetes checks before +[safeguards][topology-aware-routing-safeguards] that Kubernetes checks before setting it. 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. @@ -52,17 +56,23 @@ node the client is on and limits cross-node and cross-zone communication. ## Constraints -Kubernetes places some [constraints][topology-aware-hints-constraints] on -topology aware hints that you should review before enabling topology aware -hints on Linkerd. +Kubernetes places some [constraints][topology-aware-routing-constraints] on +topology aware routing that you should review before trying to enable topology +aware routing on Linkerd. The main things to be aware of are: -- Linkerd assumes that traffic to a given zone will be roughly proportional to - the capacity of the nodes in the zone (which can be a concern when using - horizontal pod autoscaling, as the HPA may start nodes in the "wrong" zone); - and -- The Kubernetes endpoint slice controller does not take... +- Topology aware routing assumes that traffic to a given zone will be roughly + proportional to the capacity of the nodes in the zone. This can be a concern + when using horizontal pod autoscaling, as HPA may start nodes in the "wrong" + zone. + +- Services with `internalTrafficPolicy` set to `Local` ignore topology aware + routing, by design. + +- If you have workloads running on Nodes labeled with `control-plane` or + `master` role, topology aware routing will not route to endpoints on these + Nodes. ## Configuring Topology Aware Routing @@ -75,5 +85,5 @@ time="2021-08-27T14:04:35Z" level=info msg="Establishing watch on endpoint [defa 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" ``` -[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 +[topology-aware-routing-safeguards]: https://kubernetes.io/docs/concepts/services-networking/topology-aware-hints/#safeguards +[topology-aware-routing-constraints]: https://kubernetes.io/docs/concepts/services-networking/topology-aware-hints/#constraints