From 7bf5d080dc77bbd4304d20189c6305fba91fc37a Mon Sep 17 00:00:00 2001 From: Travis Beckham Date: Thu, 25 Jun 2026 13:19:52 -0500 Subject: [PATCH 1/3] Add load biaser reference Signed-off-by: Travis Beckham --- .../content/docs/reference/rate-limiting.md | 28 +++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/linkerd.io/content/docs/reference/rate-limiting.md b/linkerd.io/content/docs/reference/rate-limiting.md index 5494d46e2f..20d526ac23 100644 --- a/linkerd.io/content/docs/reference/rate-limiting.md +++ b/linkerd.io/content/docs/reference/rate-limiting.md @@ -74,3 +74,31 @@ spec: namespace: emojivoto name: special-client ``` + +## Load Biaser + +When backends implement rate limiting and return +[HTTP 429](https://www.rfc-editor.org/rfc/rfc6585.html#page-3) or +[gRPC RESOURCE_EXHAUSTED](https://grpc.github.io/grpc/core/md_doc_statuscodes.html) +by default, the proxy treats these as successful responses from a load balancing +perspective. Since these types of responses are typically very fast, Linkerd’s +[EWMA load balancing](https://linkerd.io/docs/features/load-balancing/) may +actually send more traffic to these rate-limited endpoints. This can create a +feedback loop where clients experience high 429 or RESOURCE_EXHAUSTED rates. + +Linkerd can be configured to use a more sophisticated version of the EWMA load +balancing algorithm which takes rate-limit responses (HTTP 429 or gRPC +RESOURCE_EXHAUSTED) into account. + +To enable Linkerd to use the Load Biaser for a Service, set the following +annotation on the Service resource: + +{{< keyval >}} + +| annotation | value | +| ------------------------------------------------------- | -------------------------------------------------------------------------------------- | +| `balancer.alpha.linkerd.io/penalize-failures` | Enables the Load Biaser for this Service. Defaults to `false`. | +| `balancer.alpha.linkerd.io/load-biaser-penalty` | The latency value to inject for rate-limited responses and failures. Defaults to `5s`. | +| `balancer.alpha.linkerd.io/load-biaser-max-retry-after` | The maximum allowed value of a Retry-After header. Defaults to `300s`. | + +{{< /keyval >}} From 432f2eea0a90541d847feb0844e4e79a7d0e66ab Mon Sep 17 00:00:00 2001 From: Alex Leong Date: Thu, 25 Jun 2026 19:18:42 +0000 Subject: [PATCH 2/3] move load-biaser reference to its own page Signed-off-by: Alex Leong --- .../content/docs/reference/load-balancing.md | 37 +++++++++++++++++++ .../content/docs/reference/rate-limiting.md | 28 -------------- 2 files changed, 37 insertions(+), 28 deletions(-) create mode 100644 linkerd.io/content/docs/reference/load-balancing.md diff --git a/linkerd.io/content/docs/reference/load-balancing.md b/linkerd.io/content/docs/reference/load-balancing.md new file mode 100644 index 0000000000..6a3456b587 --- /dev/null +++ b/linkerd.io/content/docs/reference/load-balancing.md @@ -0,0 +1,37 @@ +--- +title: Load Balancing +description: How Linkerd implements load balancing. +--- + +Linkerd uses a sophisticated [EWMA load balancing algorithm](../features/load-balancing.md) +which typically requires no configuration or tuning. However, it also supports +special handling for backends which support rate limiting. This special handling +can be enabled with Service annotations. + +## Load Biaser + +When backends implement rate limiting and return +[HTTP 429](https://www.rfc-editor.org/rfc/rfc6585.html#page-3) or +[gRPC RESOURCE_EXHAUSTED](https://grpc.github.io/grpc/core/md_doc_statuscodes.html) +by default, the proxy treats these as successful responses from a load balancing +perspective. Since these types of responses are typically very fast, Linkerd’s +[EWMA load balancing](https://linkerd.io/docs/features/load-balancing/) may +actually send more traffic to these rate-limited endpoints. This can create a +feedback loop where clients experience high 429 or RESOURCE_EXHAUSTED rates. + +Linkerd can be configured to use a more sophisticated version of the EWMA load +balancing algorithm which takes rate-limit responses (HTTP 429 or gRPC +RESOURCE_EXHAUSTED) into account. + +To enable Linkerd to use the Load Biaser for a Service, set the following +annotation on the Service resource: + +{{< keyval >}} + +| annotation | value | +| ------------------------------------------------------- | -------------------------------------------------------------------------------------- | +| `balancer.alpha.linkerd.io/penalize-failures` | Enables the Load Biaser for this Service. Defaults to `false`. | +| `balancer.alpha.linkerd.io/load-biaser-penalty` | The latency value to inject for rate-limited responses and failures. Defaults to `5s`. | +| `balancer.alpha.linkerd.io/load-biaser-max-retry-after` | The maximum allowed value of a Retry-After header. Defaults to `300s`. | + +{{< /keyval >}} \ No newline at end of file diff --git a/linkerd.io/content/docs/reference/rate-limiting.md b/linkerd.io/content/docs/reference/rate-limiting.md index 20d526ac23..5494d46e2f 100644 --- a/linkerd.io/content/docs/reference/rate-limiting.md +++ b/linkerd.io/content/docs/reference/rate-limiting.md @@ -74,31 +74,3 @@ spec: namespace: emojivoto name: special-client ``` - -## Load Biaser - -When backends implement rate limiting and return -[HTTP 429](https://www.rfc-editor.org/rfc/rfc6585.html#page-3) or -[gRPC RESOURCE_EXHAUSTED](https://grpc.github.io/grpc/core/md_doc_statuscodes.html) -by default, the proxy treats these as successful responses from a load balancing -perspective. Since these types of responses are typically very fast, Linkerd’s -[EWMA load balancing](https://linkerd.io/docs/features/load-balancing/) may -actually send more traffic to these rate-limited endpoints. This can create a -feedback loop where clients experience high 429 or RESOURCE_EXHAUSTED rates. - -Linkerd can be configured to use a more sophisticated version of the EWMA load -balancing algorithm which takes rate-limit responses (HTTP 429 or gRPC -RESOURCE_EXHAUSTED) into account. - -To enable Linkerd to use the Load Biaser for a Service, set the following -annotation on the Service resource: - -{{< keyval >}} - -| annotation | value | -| ------------------------------------------------------- | -------------------------------------------------------------------------------------- | -| `balancer.alpha.linkerd.io/penalize-failures` | Enables the Load Biaser for this Service. Defaults to `false`. | -| `balancer.alpha.linkerd.io/load-biaser-penalty` | The latency value to inject for rate-limited responses and failures. Defaults to `5s`. | -| `balancer.alpha.linkerd.io/load-biaser-max-retry-after` | The maximum allowed value of a Retry-After header. Defaults to `300s`. | - -{{< /keyval >}} From 5f360664ec55a6467e10792f47a601afd939e388 Mon Sep 17 00:00:00 2001 From: Travis Beckham Date: Thu, 25 Jun 2026 14:24:21 -0500 Subject: [PATCH 3/3] Add edge doc Signed-off-by: Travis Beckham --- .../2-edge/reference/load-balancing.md | 38 +++++++++++++++++++ .../content/docs/reference/load-balancing.md | 11 +++--- 2 files changed, 44 insertions(+), 5 deletions(-) create mode 100644 linkerd.io/content/2-edge/reference/load-balancing.md diff --git a/linkerd.io/content/2-edge/reference/load-balancing.md b/linkerd.io/content/2-edge/reference/load-balancing.md new file mode 100644 index 0000000000..5691bd02e2 --- /dev/null +++ b/linkerd.io/content/2-edge/reference/load-balancing.md @@ -0,0 +1,38 @@ +--- +title: Load Balancing +description: How Linkerd implements load balancing. +--- + +Linkerd uses a sophisticated +[EWMA load balancing algorithm](../features/load-balancing.md) which typically +requires no configuration or tuning. However, it also supports special handling +for backends which support rate limiting. This special handling can be enabled +with Service annotations. + +## Load Biaser + +When backends implement rate limiting and return +[HTTP 429](https://www.rfc-editor.org/rfc/rfc6585.html#page-3) or +[gRPC RESOURCE_EXHAUSTED](https://grpc.github.io/grpc/core/md_doc_statuscodes.html) +by default, the proxy treats these as successful responses from a load balancing +perspective. Since these types of responses are typically very fast, Linkerd’s +[EWMA load balancing](https://linkerd.io/docs/features/load-balancing/) may +actually send more traffic to these rate-limited endpoints. This can create a +feedback loop where clients experience high 429 or RESOURCE_EXHAUSTED rates. + +Linkerd can be configured to use a more sophisticated version of the EWMA load +balancing algorithm which takes rate-limit responses (HTTP 429 or gRPC +RESOURCE_EXHAUSTED) into account. + +To enable Linkerd to use the Load Biaser for a Service, set the following +annotation on the Service resource: + +{{< keyval >}} + +| annotation | value | +| ------------------------------------------------------- | -------------------------------------------------------------------------------------- | +| `balancer.alpha.linkerd.io/penalize-failures` | Enables the Load Biaser for this Service. Defaults to `false`. | +| `balancer.alpha.linkerd.io/load-biaser-penalty` | The latency value to inject for rate-limited responses and failures. Defaults to `5s`. | +| `balancer.alpha.linkerd.io/load-biaser-max-retry-after` | The maximum allowed value of a Retry-After header. Defaults to `300s`. | + +{{< /keyval >}} diff --git a/linkerd.io/content/docs/reference/load-balancing.md b/linkerd.io/content/docs/reference/load-balancing.md index 6a3456b587..5691bd02e2 100644 --- a/linkerd.io/content/docs/reference/load-balancing.md +++ b/linkerd.io/content/docs/reference/load-balancing.md @@ -3,10 +3,11 @@ title: Load Balancing description: How Linkerd implements load balancing. --- -Linkerd uses a sophisticated [EWMA load balancing algorithm](../features/load-balancing.md) -which typically requires no configuration or tuning. However, it also supports -special handling for backends which support rate limiting. This special handling -can be enabled with Service annotations. +Linkerd uses a sophisticated +[EWMA load balancing algorithm](../features/load-balancing.md) which typically +requires no configuration or tuning. However, it also supports special handling +for backends which support rate limiting. This special handling can be enabled +with Service annotations. ## Load Biaser @@ -34,4 +35,4 @@ annotation on the Service resource: | `balancer.alpha.linkerd.io/load-biaser-penalty` | The latency value to inject for rate-limited responses and failures. Defaults to `5s`. | | `balancer.alpha.linkerd.io/load-biaser-max-retry-after` | The maximum allowed value of a Retry-After header. Defaults to `300s`. | -{{< /keyval >}} \ No newline at end of file +{{< /keyval >}}