From bce45b7398b6ad4d148505216d17829b80f5dfa2 Mon Sep 17 00:00:00 2001 From: Lukasz Dziedziak Date: Fri, 3 Nov 2023 14:28:46 +0100 Subject: [PATCH 01/22] feat(mlbs): create first draft Signed-off-by: Lukasz Dziedziak --- .../policies/meshloadbalancingstrategy.md | 184 ++++++++++++++++++ 1 file changed, 184 insertions(+) diff --git a/app/_src/policies/meshloadbalancingstrategy.md b/app/_src/policies/meshloadbalancingstrategy.md index ac65759d4..3a8e9a441 100644 --- a/app/_src/policies/meshloadbalancingstrategy.md +++ b/app/_src/policies/meshloadbalancingstrategy.md @@ -30,6 +30,35 @@ Locality-aware load balancing is enabled by default unlike its predecessor [loca - **`disabled`** – (optional) allows to disable locality-aware load balancing. When disabled requests are distributed across all endpoints regardless of locality. +{% if_version gte:2.5.x %} +### Advanced LocalityAwareness +Advanced locality-aware load balancing provides a more robust and straightforward method for balancing traffic within and across zones. This not only allows you to route traffic to a cross zone when the local zone service is unhealthy but also enables you to define traffic prioritization within the local zone and set cross-zone fallback priorities. + +#### LocalZone +Local zone routing allows you to specify how traffic should be routed within a local zone, prioritizing certain data planes based on tags and their associated weights. This enables you to allocate specific percentages of traffic to data planes with particular tags within the local zone. If there are no healthy endpoints within the group with the highest priority, the next priority group becomes the highest group. + +- **`localZone`** - (optional) allows to define load balancing priorities between dataplanes in the local zone. When not defined traffic is distributed equally to all endpoints within the local zone. + - **`affinityTags`** - list of tags and their weights based on which traffic is loadbalanced + - **`key`** - defines tag for which affinity is configured. The tag needs to be configured on the inbound of the service. + - **`weight`** - (optional) weight of the tag used for load balancing. The bigger the weight the higher number of requests is routed to dataplanes with specific tag. By default we will adjust them so that 90% traffic goes to first tag, 9% to next, and 1% to third and so on. + +#### CrossZone +Advanced locality-aware load balancing provides a powerful means of defining how your service should behave when there is no service available in your local zone. With this feature, you have the flexibility to configure the fallback behavior of your service, specifying the order in which it should attempt fallback options and defining different behaviors for instances located in various zones. + +- **`crossZone`** - (optional) allows to define behaviour when there is no healthy instances of the service. When not defined, cross zone traffic is disabled. + - **`failover`** - defines list of load balancing rules in order of priority. If a zone is not specified explicitly or by type `Any`, by default zone is excluded from the traffic. + - **`from`** - (optional) defines the list of zones to which the rule applies. If not specified, rule is applied to all zones. + - **`zones`** - list of zones. + - **`to`** - defines to which zones the traffic should be load balanced. + - **`type`** - defines how target zones will be picked from available zones. Available options: + - **`Any`** - traffic will be load balanced to every available zone. + - **`Only`** - traffic will be load balanced only to zones specified in zones list. + - **`AnyExcept`** - traffic will be load balanced to every available zone except these specified in zones list. + - **`None`** - traffic will not be load balanced to any zone. + - **`zones`** - names of zones + - **`failoverThreshold.percentage`** - (optional) defines the percentage of live destination dataplane proxies below which load balancing to the next priority starts. Default: 50% + +{% endif_version %} ### LoadBalancer @@ -237,6 +266,161 @@ Apply the configuration with `kumactl apply -f [..]` or with the [HTTP API](/doc {% endtab %} {% endtabs %} +{% if_version gte:2.5.x %} +### Disable cross zone traffic and prioritize traffic the dataplanes on the same node and availability zone + +Requests to `backend` will be spread based on default weights and won't leave the local zone. +In this example, whenever user sends a request to `backend` service 90% of requests will arrive to the instance with the same value of `k8s.io/node` tag, 9% of requests to the instance with the same value as caller of tag `k8s.io/az`, and 1% to rest of instances. + +{% tabs local-zone-affinity-backend useUrlFragment=false %} +{% tab local-zone-affinity-backend Kubernetes %} + +```yaml +kind: MeshLoadBalancingStrategy +apiVersion: kuma.io/v1alpha1 +metadata: + name: local-zone-affinity-backend + namespace: {{site.mesh_namespace}} + labels: + kuma.io/mesh: mesh-1 +spec: + targetRef: + kind: Mesh + to: + - targetRef: + kind: MeshService + name: backend + default: + localityAwareness: + localZone: + affinityTags: + - key: k8s.io/node + - key: k8s.io/az +``` + +Apply the configuration with `kubectl apply -f [..]`. + +{% endtab %} +{% tab local-zone-affinity-backend Universal %} + +```yaml +type: MeshLoadBalancingStrategy +name: local-zone-affinity-backend +mesh: mesh-1 +spec: + targetRef: + kind: Mesh + to: + - targetRef: + kind: MeshService + name: backend + default: + localityAwareness: + localZone: + affinityTags: + - key: k8s.io/node + - key: k8s.io/az +``` + +Apply the configuration with `kumactl apply -f [..]` or with the [HTTP API](/docs/{{ page.version }}/reference/http-api). + +{% endtab %} +{% endtabs %} + +### Prioritize traffic to dataplanes within the same datacenter and fallback cross zone in specific order + +Requests to backend will be distributed based on weights, with 99.9% of requests routed to data planes in the same datacenter, 0.001% to data planes in the same region, and the remainder to other local instances. + +When there are no healthy backends within the local zone, traffic from data planes in zones `us-1`, `us-2`, and `us-3` will only fall back to zones `us-1`, `us-2`, and `us-3`. If there are no healthy instances in these zones, requests from any instance will then fall back to `us-4`. If there are no healthy instances in `us-4`, the request will fail, as the last rule, by default, has type: `None`, meaning no fallback is allowed. + +{% tabs local-zone-affinity-cross-backend useUrlFragment=false %} +{% tab local-zone-affinity-cross-backend Kubernetes %} + +```yaml +kind: MeshLoadBalancingStrategy +apiVersion: kuma.io/v1alpha1 +metadata: + name: local-zone-affinity-cross-backend + namespace: {{site.mesh_namespace}} + labels: + kuma.io/mesh: mesh-1 +spec: + targetRef: + kind: Mesh + to: + - targetRef: + kind: MeshService + name: backend + default: + localityAwareness: + localZone: + affinityTags: + - key: infra.io/datacenter + weight: 9000 + - key: infra.io/region + weight: 9 + crossZone: + failover: + - from: + zones: ["us-1", "us-2", "us-3"] + to: + type: Only + zones: ["us-1", "us-2", "us-3"] + - from: + zones: ["eu-1", "eu-2", "eu-2"] + to: + type: Only + zones: ["eu-1", "eu-2", "eu-2"] + - to: + type: Only + zones: ["us-4"] +``` + +Apply the configuration with `kubectl apply -f [..]`. + +{% endtab %} +{% tab local-zone-affinity-cross-backend Universal %} + +```yaml +type: MeshLoadBalancingStrategy +name: local-zone-affinity-cross-backend +mesh: mesh-1 +spec: + targetRef: + kind: Mesh + to: + - targetRef: + kind: MeshService + name: backend + default: + localityAwareness: + localZone: + affinityTags: + - key: infra.io/datacenter + weight: 9000 + - key: infra.io/region + weight: 9 + crossZone: + failover: + - from: + zones: ["us-1", "us-2", "us-3"] + to: + type: Only + zones: ["us-1", "us-2", "us-3"] + - from: + zones: ["eu-1", "eu-2", "eu-2"] + to: + type: Only + zones: ["eu-1", "eu-2", "eu-2"] +``` + +Apply the configuration with `kumactl apply -f [..]` or with the [HTTP API](/docs/{{ page.version }}/reference/http-api). + +{% endtab %} +{% endtabs %} + +{% endif_version %} + ## All policy options {% json_schema MeshLoadBalancingStrategies %} From 56941548da970f6e76067afb1c4a4b3598821d02 Mon Sep 17 00:00:00 2001 From: Lukasz Dziedziak Date: Fri, 3 Nov 2023 18:20:34 +0100 Subject: [PATCH 02/22] more docs Signed-off-by: Lukasz Dziedziak --- app/_src/policies/meshloadbalancingstrategy.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/app/_src/policies/meshloadbalancingstrategy.md b/app/_src/policies/meshloadbalancingstrategy.md index 3a8e9a441..333d7e263 100644 --- a/app/_src/policies/meshloadbalancingstrategy.md +++ b/app/_src/policies/meshloadbalancingstrategy.md @@ -39,7 +39,7 @@ Local zone routing allows you to specify how traffic should be routed within a l - **`localZone`** - (optional) allows to define load balancing priorities between dataplanes in the local zone. When not defined traffic is distributed equally to all endpoints within the local zone. - **`affinityTags`** - list of tags and their weights based on which traffic is loadbalanced - - **`key`** - defines tag for which affinity is configured. The tag needs to be configured on the inbound of the service. + - **`key`** - defines tag for which affinity is configured. The tag needs to be configured on the inbound of the service. In case of Kubernetes pod needs to have a tag and it should be propagated. On Universal user needs to define it on the inbound of the service. In case there so match, the dataplane match to the last group with the lowest weight. - **`weight`** - (optional) weight of the tag used for load balancing. The bigger the weight the higher number of requests is routed to dataplanes with specific tag. By default we will adjust them so that 90% traffic goes to first tag, 9% to next, and 1% to third and so on. #### CrossZone From c9eb23f2693dd107b9ed60c6eea0c2f16da4c95e Mon Sep 17 00:00:00 2001 From: Lukasz Dziedziak Date: Mon, 6 Nov 2023 12:24:54 +0100 Subject: [PATCH 03/22] add more details Signed-off-by: Lukasz Dziedziak --- .../policies/meshloadbalancingstrategy.md | 90 +++++++++++++++++-- 1 file changed, 84 insertions(+), 6 deletions(-) diff --git a/app/_src/policies/meshloadbalancingstrategy.md b/app/_src/policies/meshloadbalancingstrategy.md index 333d7e263..3f5e5946d 100644 --- a/app/_src/policies/meshloadbalancingstrategy.md +++ b/app/_src/policies/meshloadbalancingstrategy.md @@ -35,7 +35,7 @@ across all endpoints regardless of locality. Advanced locality-aware load balancing provides a more robust and straightforward method for balancing traffic within and across zones. This not only allows you to route traffic to a cross zone when the local zone service is unhealthy but also enables you to define traffic prioritization within the local zone and set cross-zone fallback priorities. #### LocalZone -Local zone routing allows you to specify how traffic should be routed within a local zone, prioritizing certain data planes based on tags and their associated weights. This enables you to allocate specific percentages of traffic to data planes with particular tags within the local zone. If there are no healthy endpoints within the group with the highest priority, the next priority group becomes the highest group. +Local zone routing allows you to define traffic routing rules within a local zone, prioritizing data planes based on tags and their associated weights. This enables you to allocate specific traffic percentages to data planes with particular tags within the local zone. If there are no healthy endpoints within the highest priority group, the next priority group takes precedence. Locality awareness within the local zone relies on tags within inbounds, so it's crucial to ensure that the tags used in the policy are defined for the service (Dataplane object on Universal, Deployment annotations on Kubernetes). - **`localZone`** - (optional) allows to define load balancing priorities between dataplanes in the local zone. When not defined traffic is distributed equally to all endpoints within the local zone. - **`affinityTags`** - list of tags and their weights based on which traffic is loadbalanced @@ -43,7 +43,7 @@ Local zone routing allows you to specify how traffic should be routed within a l - **`weight`** - (optional) weight of the tag used for load balancing. The bigger the weight the higher number of requests is routed to dataplanes with specific tag. By default we will adjust them so that 90% traffic goes to first tag, 9% to next, and 1% to third and so on. #### CrossZone -Advanced locality-aware load balancing provides a powerful means of defining how your service should behave when there is no service available in your local zone. With this feature, you have the flexibility to configure the fallback behavior of your service, specifying the order in which it should attempt fallback options and defining different behaviors for instances located in various zones. +Advanced locality-aware load balancing provides a powerful means of defining how your service should behave when there is no service available in your local zone. With this feature, you have the flexibility to configure the fallback behavior of your service, specifying the order in which it should attempt fallback options and defining different behaviors for instances located in various zones. - **`crossZone`** - (optional) allows to define behaviour when there is no healthy instances of the service. When not defined, cross zone traffic is disabled. - **`failover`** - defines list of load balancing rules in order of priority. If a zone is not specified explicitly or by type `Any`, by default zone is excluded from the traffic. @@ -327,6 +327,81 @@ Apply the configuration with `kumactl apply -f [..]` or with the [HTTP API](/doc {% endtab %} {% endtabs %} +### Route within the local zone equally, but specify cross zone order + +Requests to the backend service will be evenly distributed among all endpoints within the local zone. If there are fewer than 25% healthy hosts in the local zone, traffic will be redirected to other zones. Initially, traffic will be sent to the `us-1` zone. In the event that the `us-1` zone becomes unavailable, traffic will then be directed to all zones, except for `us-2` and `us-3`. If these zones are also found to have unhealthy hosts, the traffic will be rerouted to `us-2` and `us-3`. + +{% tabs cross-zone-backend useUrlFragment=false %} +{% tab cross-zone-backend Kubernetes %} + +```yaml +kind: MeshLoadBalancingStrategy +apiVersion: kuma.io/v1alpha1 +metadata: + name: cross-zone-backend + namespace: {{site.mesh_namespace}} + labels: + kuma.io/mesh: mesh-1 +spec: + targetRef: + kind: Mesh + to: + - targetRef: + kind: MeshService + name: backend + default: + localityAwareness: + crossZone: + failover: + - to: + type: Only + zones: ["us-1"] + - to: + type: AnyExcept + zones: ["us-2", "us-3"] + - to: + type: Any + failoverThreshold: + percentage: 25 +``` + +Apply the configuration with `kubectl apply -f [..]`. + +{% endtab %} +{% tab cross-zone-backend Universal %} + +```yaml +type: MeshLoadBalancingStrategy +name: cross-zone-backend +mesh: mesh-1 +spec: + targetRef: + kind: Mesh + to: + - targetRef: + kind: MeshService + name: backend + default: + localityAwareness: + crossZone: + failover: + - to: + type: Only + zones: ["us-1"] + - to: + type: AnyExcept + zones: ["us-2", "us-3"] + - to: + type: Any + failoverThreshold: + percentage: 25 +``` + +Apply the configuration with `kumactl apply -f [..]` or with the [HTTP API](/docs/{{ page.version }}/reference/http-api). + +{% endtab %} +{% endtabs %} + ### Prioritize traffic to dataplanes within the same datacenter and fallback cross zone in specific order Requests to backend will be distributed based on weights, with 99.9% of requests routed to data planes in the same datacenter, 0.001% to data planes in the same region, and the remainder to other local instances. @@ -367,10 +442,10 @@ spec: type: Only zones: ["us-1", "us-2", "us-3"] - from: - zones: ["eu-1", "eu-2", "eu-2"] + zones: ["eu-1", "eu-2", "eu-3"] to: type: Only - zones: ["eu-1", "eu-2", "eu-2"] + zones: ["eu-1", "eu-2", "eu-3"] - to: type: Only zones: ["us-4"] @@ -408,10 +483,13 @@ spec: type: Only zones: ["us-1", "us-2", "us-3"] - from: - zones: ["eu-1", "eu-2", "eu-2"] + zones: ["eu-1", "eu-2", "eu-3"] to: type: Only - zones: ["eu-1", "eu-2", "eu-2"] + zones: ["eu-1", "eu-2", "eu-3"] + - to: + type: Only + zones: ["us-4"] ``` Apply the configuration with `kumactl apply -f [..]` or with the [HTTP API](/docs/{{ page.version }}/reference/http-api). From 002d3514589e85467653e7a2b6b1422a6d56c8d0 Mon Sep 17 00:00:00 2001 From: Lukasz Dziedziak Date: Wed, 8 Nov 2023 12:16:28 +0100 Subject: [PATCH 04/22] add warning about mtls Signed-off-by: Lukasz Dziedziak --- app/_src/policies/meshloadbalancingstrategy.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/app/_src/policies/meshloadbalancingstrategy.md b/app/_src/policies/meshloadbalancingstrategy.md index 3f5e5946d..d860810b4 100644 --- a/app/_src/policies/meshloadbalancingstrategy.md +++ b/app/_src/policies/meshloadbalancingstrategy.md @@ -43,6 +43,9 @@ Local zone routing allows you to define traffic routing rules within a local zon - **`weight`** - (optional) weight of the tag used for load balancing. The bigger the weight the higher number of requests is routed to dataplanes with specific tag. By default we will adjust them so that 90% traffic goes to first tag, 9% to next, and 1% to third and so on. #### CrossZone +{% warning %} +Remember that cross-zone traffic requires [mTLS enabled](/docs/{{ page.version}}/mutual-tls). +{% endwarning %} Advanced locality-aware load balancing provides a powerful means of defining how your service should behave when there is no service available in your local zone. With this feature, you have the flexibility to configure the fallback behavior of your service, specifying the order in which it should attempt fallback options and defining different behaviors for instances located in various zones. - **`crossZone`** - (optional) allows to define behaviour when there is no healthy instances of the service. When not defined, cross zone traffic is disabled. From 2a9184a11074fbe774c1717184c6837d9fb990f4 Mon Sep 17 00:00:00 2001 From: Lukasz Dziedziak Date: Wed, 8 Nov 2023 12:36:21 +0100 Subject: [PATCH 05/22] fix link Signed-off-by: Lukasz Dziedziak --- app/_src/policies/meshloadbalancingstrategy.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/app/_src/policies/meshloadbalancingstrategy.md b/app/_src/policies/meshloadbalancingstrategy.md index d860810b4..1c7b7debf 100644 --- a/app/_src/policies/meshloadbalancingstrategy.md +++ b/app/_src/policies/meshloadbalancingstrategy.md @@ -44,7 +44,7 @@ Local zone routing allows you to define traffic routing rules within a local zon #### CrossZone {% warning %} -Remember that cross-zone traffic requires [mTLS enabled](/docs/{{ page.version}}/mutual-tls). +Remember that cross-zone traffic requires [mTLS enabled](/docs/{{ page.version}}/policies/mutual-tls). {% endwarning %} Advanced locality-aware load balancing provides a powerful means of defining how your service should behave when there is no service available in your local zone. With this feature, you have the flexibility to configure the fallback behavior of your service, specifying the order in which it should attempt fallback options and defining different behaviors for instances located in various zones. From f2d890f02794f292466a03e5839ca42a31ff09bf Mon Sep 17 00:00:00 2001 From: Lukasz Dziedziak Date: Fri, 10 Nov 2023 12:37:52 +0100 Subject: [PATCH 06/22] review Signed-off-by: Lukasz Dziedziak --- .../policies/meshloadbalancingstrategy.md | 75 +++++++++---------- 1 file changed, 37 insertions(+), 38 deletions(-) diff --git a/app/_src/policies/meshloadbalancingstrategy.md b/app/_src/policies/meshloadbalancingstrategy.md index 1c7b7debf..fd177cdcf 100644 --- a/app/_src/policies/meshloadbalancingstrategy.md +++ b/app/_src/policies/meshloadbalancingstrategy.md @@ -32,14 +32,14 @@ across all endpoints regardless of locality. {% if_version gte:2.5.x %} ### Advanced LocalityAwareness -Advanced locality-aware load balancing provides a more robust and straightforward method for balancing traffic within and across zones. This not only allows you to route traffic to a cross zone when the local zone service is unhealthy but also enables you to define traffic prioritization within the local zone and set cross-zone fallback priorities. +Advanced locality-aware load balancing provides a more robust and straightforward method for balancing traffic within and across zones. This not only allows you to route traffic across zones when the local zone service is unhealthy but also enables you to define traffic prioritization within the local zone and set cross-zone fallback priorities. #### LocalZone Local zone routing allows you to define traffic routing rules within a local zone, prioritizing data planes based on tags and their associated weights. This enables you to allocate specific traffic percentages to data planes with particular tags within the local zone. If there are no healthy endpoints within the highest priority group, the next priority group takes precedence. Locality awareness within the local zone relies on tags within inbounds, so it's crucial to ensure that the tags used in the policy are defined for the service (Dataplane object on Universal, Deployment annotations on Kubernetes). -- **`localZone`** - (optional) allows to define load balancing priorities between dataplanes in the local zone. When not defined traffic is distributed equally to all endpoints within the local zone. - - **`affinityTags`** - list of tags and their weights based on which traffic is loadbalanced - - **`key`** - defines tag for which affinity is configured. The tag needs to be configured on the inbound of the service. In case of Kubernetes pod needs to have a tag and it should be propagated. On Universal user needs to define it on the inbound of the service. In case there so match, the dataplane match to the last group with the lowest weight. +- **`localZone`** - (optional) allows to define load balancing priorities between dataplanes in the local zone. When not defined, traffic is distributed equally to all endpoints within the local zone. + - **`affinityTags`** - list of tags and their weights based on which traffic is load balanced + - **`key`** - defines tag for which affinity is configured. The tag needs to be configured on the inbound of the service. In case of Kubernetes, pod needs to have an annotations or a label. On Universal user needs to define it on the inbound of the service. In case there no match, the dataplane match to the last group with the lowest weight. - **`weight`** - (optional) weight of the tag used for load balancing. The bigger the weight the higher number of requests is routed to dataplanes with specific tag. By default we will adjust them so that 90% traffic goes to first tag, 9% to next, and 1% to third and so on. #### CrossZone @@ -49,7 +49,7 @@ Remember that cross-zone traffic requires [mTLS enabled](/docs/{{ page.version}} Advanced locality-aware load balancing provides a powerful means of defining how your service should behave when there is no service available in your local zone. With this feature, you have the flexibility to configure the fallback behavior of your service, specifying the order in which it should attempt fallback options and defining different behaviors for instances located in various zones. - **`crossZone`** - (optional) allows to define behaviour when there is no healthy instances of the service. When not defined, cross zone traffic is disabled. - - **`failover`** - defines list of load balancing rules in order of priority. If a zone is not specified explicitly or by type `Any`, by default zone is excluded from the traffic. + - **`failover`** - defines a list of load balancing rules in order of priority. If a zone is not specified explicitly by name or implicitly using the type `Any`/`AnyExcept`/`Only` it is excluded from receiving traffic. - **`from`** - (optional) defines the list of zones to which the rule applies. If not specified, rule is applied to all zones. - **`zones`** - list of zones. - **`to`** - defines to which zones the traffic should be load balanced. @@ -272,8 +272,7 @@ Apply the configuration with `kumactl apply -f [..]` or with the [HTTP API](/doc {% if_version gte:2.5.x %} ### Disable cross zone traffic and prioritize traffic the dataplanes on the same node and availability zone -Requests to `backend` will be spread based on default weights and won't leave the local zone. -In this example, whenever user sends a request to `backend` service 90% of requests will arrive to the instance with the same value of `k8s.io/node` tag, 9% of requests to the instance with the same value as caller of tag `k8s.io/az`, and 1% to rest of instances. +In this example, whenever a user sends a request to the `backend` service, 90% of the requests will arrive at the instance with the same value of the `k8s.io/node` tag, 9% of the requests will go to the instance with the same value as the caller of the `k8s.io/az` tag, and 1% will go to the rest of the instances. {% tabs local-zone-affinity-backend useUrlFragment=false %} {% tab local-zone-affinity-backend Kubernetes %} @@ -409,7 +408,7 @@ Apply the configuration with `kumactl apply -f [..]` or with the [HTTP API](/doc Requests to backend will be distributed based on weights, with 99.9% of requests routed to data planes in the same datacenter, 0.001% to data planes in the same region, and the remainder to other local instances. -When there are no healthy backends within the local zone, traffic from data planes in zones `us-1`, `us-2`, and `us-3` will only fall back to zones `us-1`, `us-2`, and `us-3`. If there are no healthy instances in these zones, requests from any instance will then fall back to `us-4`. If there are no healthy instances in `us-4`, the request will fail, as the last rule, by default, has type: `None`, meaning no fallback is allowed. +When no healthy backends are available within the local zone, traffic from data planes in zones `us-1`, `us-2`, and `us-3` will only fall back to zones `us-1`, `us-2`, and `us-3`, while in zones `eu-1`, `eu-2`, and `eu-3` will only fall back to zones `eu-1`, `eu-2`, and `eu-3`. If there are no healthy instances in all zones `eu-[1-3]` or `us-[1-3]`, requests from any instance will then fall back to `us-4`. If there are no healthy instances in `us-4`, the request will fail, as the last rule, by default, has a type of `None`, meaning no fallback is allowed. {% tabs local-zone-affinity-cross-backend useUrlFragment=false %} {% tab local-zone-affinity-cross-backend Kubernetes %} @@ -437,21 +436,21 @@ spec: weight: 9000 - key: infra.io/region weight: 9 - crossZone: - failover: - - from: - zones: ["us-1", "us-2", "us-3"] - to: - type: Only - zones: ["us-1", "us-2", "us-3"] - - from: - zones: ["eu-1", "eu-2", "eu-3"] - to: - type: Only - zones: ["eu-1", "eu-2", "eu-3"] - - to: - type: Only - zones: ["us-4"] + crossZone: + failover: + - from: + zones: ["us-1", "us-2", "us-3"] + to: + type: Only + zones: ["us-1", "us-2", "us-3"] + - from: + zones: ["eu-1", "eu-2", "eu-3"] + to: + type: Only + zones: ["eu-1", "eu-2", "eu-3"] + - to: + type: Only + zones: ["us-4"] ``` Apply the configuration with `kubectl apply -f [..]`. @@ -478,21 +477,21 @@ spec: weight: 9000 - key: infra.io/region weight: 9 - crossZone: - failover: - - from: - zones: ["us-1", "us-2", "us-3"] - to: - type: Only - zones: ["us-1", "us-2", "us-3"] - - from: - zones: ["eu-1", "eu-2", "eu-3"] - to: - type: Only - zones: ["eu-1", "eu-2", "eu-3"] - - to: - type: Only - zones: ["us-4"] + crossZone: + failover: + - from: + zones: ["us-1", "us-2", "us-3"] + to: + type: Only + zones: ["us-1", "us-2", "us-3"] + - from: + zones: ["eu-1", "eu-2", "eu-3"] + to: + type: Only + zones: ["eu-1", "eu-2", "eu-3"] + - to: + type: Only + zones: ["us-4"] ``` Apply the configuration with `kumactl apply -f [..]` or with the [HTTP API](/docs/{{ page.version }}/reference/http-api). From d5bf660ecfc4b5a9069af23b56d4fa4f66039260 Mon Sep 17 00:00:00 2001 From: Lukasz Dziedziak Date: Fri, 10 Nov 2023 12:40:02 +0100 Subject: [PATCH 07/22] added more context Signed-off-by: Lukasz Dziedziak --- app/_src/policies/meshloadbalancingstrategy.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/app/_src/policies/meshloadbalancingstrategy.md b/app/_src/policies/meshloadbalancingstrategy.md index fd177cdcf..1faa2bb79 100644 --- a/app/_src/policies/meshloadbalancingstrategy.md +++ b/app/_src/policies/meshloadbalancingstrategy.md @@ -49,7 +49,7 @@ Remember that cross-zone traffic requires [mTLS enabled](/docs/{{ page.version}} Advanced locality-aware load balancing provides a powerful means of defining how your service should behave when there is no service available in your local zone. With this feature, you have the flexibility to configure the fallback behavior of your service, specifying the order in which it should attempt fallback options and defining different behaviors for instances located in various zones. - **`crossZone`** - (optional) allows to define behaviour when there is no healthy instances of the service. When not defined, cross zone traffic is disabled. - - **`failover`** - defines a list of load balancing rules in order of priority. If a zone is not specified explicitly by name or implicitly using the type `Any`/`AnyExcept`/`Only` it is excluded from receiving traffic. + - **`failover`** - defines a list of load balancing rules in order of priority. If a zone is not specified explicitly by name or implicitly using the type `Any`/`AnyExcept` it is excluded from receiving traffic. By default, the last rule is always `None` which means, that there is no traffic to other zones after specified rules. - **`from`** - (optional) defines the list of zones to which the rule applies. If not specified, rule is applied to all zones. - **`zones`** - list of zones. - **`to`** - defines to which zones the traffic should be load balanced. From a64aed89cfaec20d10318c148fba99e4bee8fc72 Mon Sep 17 00:00:00 2001 From: Lukasz Dziedziak Date: Fri, 10 Nov 2023 12:43:26 +0100 Subject: [PATCH 08/22] switch to policy yaml Signed-off-by: Lukasz Dziedziak --- .../policies/meshloadbalancingstrategy.md | 140 +----------------- 1 file changed, 6 insertions(+), 134 deletions(-) diff --git a/app/_src/policies/meshloadbalancingstrategy.md b/app/_src/policies/meshloadbalancingstrategy.md index 1faa2bb79..fcf8b84bc 100644 --- a/app/_src/policies/meshloadbalancingstrategy.md +++ b/app/_src/policies/meshloadbalancingstrategy.md @@ -274,37 +274,7 @@ Apply the configuration with `kumactl apply -f [..]` or with the [HTTP API](/doc In this example, whenever a user sends a request to the `backend` service, 90% of the requests will arrive at the instance with the same value of the `k8s.io/node` tag, 9% of the requests will go to the instance with the same value as the caller of the `k8s.io/az` tag, and 1% will go to the rest of the instances. -{% tabs local-zone-affinity-backend useUrlFragment=false %} -{% tab local-zone-affinity-backend Kubernetes %} - -```yaml -kind: MeshLoadBalancingStrategy -apiVersion: kuma.io/v1alpha1 -metadata: - name: local-zone-affinity-backend - namespace: {{site.mesh_namespace}} - labels: - kuma.io/mesh: mesh-1 -spec: - targetRef: - kind: Mesh - to: - - targetRef: - kind: MeshService - name: backend - default: - localityAwareness: - localZone: - affinityTags: - - key: k8s.io/node - - key: k8s.io/az -``` - -Apply the configuration with `kubectl apply -f [..]`. - -{% endtab %} -{% tab local-zone-affinity-backend Universal %} - +{% policy_yaml local-zone-affinity-backend %} ```yaml type: MeshLoadBalancingStrategy name: local-zone-affinity-backend @@ -323,55 +293,13 @@ spec: - key: k8s.io/node - key: k8s.io/az ``` - -Apply the configuration with `kumactl apply -f [..]` or with the [HTTP API](/docs/{{ page.version }}/reference/http-api). - -{% endtab %} -{% endtabs %} +{% endpolicy_yaml %} ### Route within the local zone equally, but specify cross zone order Requests to the backend service will be evenly distributed among all endpoints within the local zone. If there are fewer than 25% healthy hosts in the local zone, traffic will be redirected to other zones. Initially, traffic will be sent to the `us-1` zone. In the event that the `us-1` zone becomes unavailable, traffic will then be directed to all zones, except for `us-2` and `us-3`. If these zones are also found to have unhealthy hosts, the traffic will be rerouted to `us-2` and `us-3`. -{% tabs cross-zone-backend useUrlFragment=false %} -{% tab cross-zone-backend Kubernetes %} - -```yaml -kind: MeshLoadBalancingStrategy -apiVersion: kuma.io/v1alpha1 -metadata: - name: cross-zone-backend - namespace: {{site.mesh_namespace}} - labels: - kuma.io/mesh: mesh-1 -spec: - targetRef: - kind: Mesh - to: - - targetRef: - kind: MeshService - name: backend - default: - localityAwareness: - crossZone: - failover: - - to: - type: Only - zones: ["us-1"] - - to: - type: AnyExcept - zones: ["us-2", "us-3"] - - to: - type: Any - failoverThreshold: - percentage: 25 -``` - -Apply the configuration with `kubectl apply -f [..]`. - -{% endtab %} -{% tab cross-zone-backend Universal %} - +{% policy_yaml cross-zone-backend %} ```yaml type: MeshLoadBalancingStrategy name: cross-zone-backend @@ -398,11 +326,7 @@ spec: failoverThreshold: percentage: 25 ``` - -Apply the configuration with `kumactl apply -f [..]` or with the [HTTP API](/docs/{{ page.version }}/reference/http-api). - -{% endtab %} -{% endtabs %} +{% endpolicy_yaml %} ### Prioritize traffic to dataplanes within the same datacenter and fallback cross zone in specific order @@ -410,54 +334,7 @@ Requests to backend will be distributed based on weights, with 99.9% of requests When no healthy backends are available within the local zone, traffic from data planes in zones `us-1`, `us-2`, and `us-3` will only fall back to zones `us-1`, `us-2`, and `us-3`, while in zones `eu-1`, `eu-2`, and `eu-3` will only fall back to zones `eu-1`, `eu-2`, and `eu-3`. If there are no healthy instances in all zones `eu-[1-3]` or `us-[1-3]`, requests from any instance will then fall back to `us-4`. If there are no healthy instances in `us-4`, the request will fail, as the last rule, by default, has a type of `None`, meaning no fallback is allowed. -{% tabs local-zone-affinity-cross-backend useUrlFragment=false %} -{% tab local-zone-affinity-cross-backend Kubernetes %} - -```yaml -kind: MeshLoadBalancingStrategy -apiVersion: kuma.io/v1alpha1 -metadata: - name: local-zone-affinity-cross-backend - namespace: {{site.mesh_namespace}} - labels: - kuma.io/mesh: mesh-1 -spec: - targetRef: - kind: Mesh - to: - - targetRef: - kind: MeshService - name: backend - default: - localityAwareness: - localZone: - affinityTags: - - key: infra.io/datacenter - weight: 9000 - - key: infra.io/region - weight: 9 - crossZone: - failover: - - from: - zones: ["us-1", "us-2", "us-3"] - to: - type: Only - zones: ["us-1", "us-2", "us-3"] - - from: - zones: ["eu-1", "eu-2", "eu-3"] - to: - type: Only - zones: ["eu-1", "eu-2", "eu-3"] - - to: - type: Only - zones: ["us-4"] -``` - -Apply the configuration with `kubectl apply -f [..]`. - -{% endtab %} -{% tab local-zone-affinity-cross-backend Universal %} - +{% policy_yaml local-zone-affinity-cross-backend %} ```yaml type: MeshLoadBalancingStrategy name: local-zone-affinity-cross-backend @@ -493,12 +370,7 @@ spec: type: Only zones: ["us-4"] ``` - -Apply the configuration with `kumactl apply -f [..]` or with the [HTTP API](/docs/{{ page.version }}/reference/http-api). - -{% endtab %} -{% endtabs %} - +{% endpolicy_yaml %} {% endif_version %} ## All policy options From a2171887219f12057d3c9861eeda01d8a127b7df Mon Sep 17 00:00:00 2001 From: Lukasz Dziedziak Date: Fri, 10 Nov 2023 12:52:25 +0100 Subject: [PATCH 09/22] added more examples Signed-off-by: Lukasz Dziedziak --- .../policies/meshloadbalancingstrategy.md | 43 +++++++++++++++++++ 1 file changed, 43 insertions(+) diff --git a/app/_src/policies/meshloadbalancingstrategy.md b/app/_src/policies/meshloadbalancingstrategy.md index fcf8b84bc..f9e85a2b0 100644 --- a/app/_src/policies/meshloadbalancingstrategy.md +++ b/app/_src/policies/meshloadbalancingstrategy.md @@ -295,6 +295,49 @@ spec: ``` {% endpolicy_yaml %} +### Disable cross zone traffic and route to the local zone instances equally + +In this example, when a user sends a request to the backend service, the request is routed equally to all instances in the local zone. If there are no instances in the local zone, the request will fail because there is no cross-zone traffic. + +{% policy_yaml local-zone-affinity-backend-2 %} +```yaml +type: MeshLoadBalancingStrategy +name: local-zone-affinity-backend +mesh: mesh-1 +spec: + targetRef: + kind: Mesh + to: + - targetRef: + kind: MeshService + name: backend + default: + localityAwareness: + localZone: + affinityTags: [] +``` +{% endpolicy_yaml %} + +or + +{% policy_yaml local-zone-affinity-backend-3 %} +```yaml +type: MeshLoadBalancingStrategy +name: local-zone-affinity-backend +mesh: mesh-1 +spec: + targetRef: + kind: Mesh + to: + - targetRef: + kind: MeshService + name: backend + default: + localityAwareness: + localZone: {} +``` +{% endpolicy_yaml %} + ### Route within the local zone equally, but specify cross zone order Requests to the backend service will be evenly distributed among all endpoints within the local zone. If there are fewer than 25% healthy hosts in the local zone, traffic will be redirected to other zones. Initially, traffic will be sent to the `us-1` zone. In the event that the `us-1` zone becomes unavailable, traffic will then be directed to all zones, except for `us-2` and `us-3`. If these zones are also found to have unhealthy hosts, the traffic will be rerouted to `us-2` and `us-3`. From 8cc762aaeef359148fd5a008e3a6325b836912d2 Mon Sep 17 00:00:00 2001 From: Marcin Skalski Date: Fri, 10 Nov 2023 15:28:12 +0100 Subject: [PATCH 10/22] add Zone Egress docs --- app/_src/policies/meshloadbalancingstrategy.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/app/_src/policies/meshloadbalancingstrategy.md b/app/_src/policies/meshloadbalancingstrategy.md index f9e85a2b0..de99f5d4f 100644 --- a/app/_src/policies/meshloadbalancingstrategy.md +++ b/app/_src/policies/meshloadbalancingstrategy.md @@ -61,6 +61,15 @@ Advanced locality-aware load balancing provides a powerful means of defining how - **`zones`** - names of zones - **`failoverThreshold.percentage`** - (optional) defines the percentage of live destination dataplane proxies below which load balancing to the next priority starts. Default: 50% +#### Zone Egress support + +Using Zone Egress Proxy in multizone deployment poses certain limitations for this policy. When configuring `MeshLoadbalancingStrategy` with Zone Egress you can only use `Mesh` as a top level targetRef. This is because we don't differentiate requests that come to Zone Egress from different clients, yet. + +Moreover, Zone Egress is a simple proxy that uses a long living L4 connection between Zone Ingress. Because of this, when new `MeshLoadbalancingStrategy` with locality awareness is configured, we won’t refresh connections and locality awareness will apply only to new connections. + +Another thing you need to be aware of is that when you use the `MeshCircuitBreaker`'s outlier detection to keep track of healthy endpoints. Normally, you would use `MeshCircuitBreaker` to act on failures and trigger traffic redirect to the next priority level if the number of healthy endpoints fall below crossZone `failoverThreshold`. When you have a single instance of Zone Egress, all remote zones will be behind a single endpoint. Since `MeshCircuitBreaker` is configured on Data Plane Proxy, when one of the zones start responding with errors it will mark the whole Zone Egress as not healthy and won’t send traffic there even though there could be multiple zones with live endpoints. + + {% endif_version %} ### LoadBalancer From 5e655a63ad04e0651beeb0c34dbadf998c478a2d Mon Sep 17 00:00:00 2001 From: Marcin Skalski Date: Mon, 13 Nov 2023 10:10:48 +0100 Subject: [PATCH 11/22] Update app/_src/policies/meshloadbalancingstrategy.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Krzysztof Słonka Signed-off-by: Marcin Skalski --- app/_src/policies/meshloadbalancingstrategy.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/app/_src/policies/meshloadbalancingstrategy.md b/app/_src/policies/meshloadbalancingstrategy.md index d3a93376f..73e188c14 100644 --- a/app/_src/policies/meshloadbalancingstrategy.md +++ b/app/_src/policies/meshloadbalancingstrategy.md @@ -65,7 +65,7 @@ Advanced locality-aware load balancing provides a powerful means of defining how Using Zone Egress Proxy in multizone deployment poses certain limitations for this policy. When configuring `MeshLoadbalancingStrategy` with Zone Egress you can only use `Mesh` as a top level targetRef. This is because we don't differentiate requests that come to Zone Egress from different clients, yet. -Moreover, Zone Egress is a simple proxy that uses a long living L4 connection between Zone Ingress. Because of this, when new `MeshLoadbalancingStrategy` with locality awareness is configured, we won’t refresh connections and locality awareness will apply only to new connections. +Moreover, Zone Egress is a simple proxy that uses a long-living L4 connection to Zone Ingress. Consequently, when a new `MeshLoadbalancingStrategy` with locality awareness is configured, connections won’t be refreshed, and locality awareness will apply only to new connections. Another thing you need to be aware of is that when you use the `MeshCircuitBreaker`'s outlier detection to keep track of healthy endpoints. Normally, you would use `MeshCircuitBreaker` to act on failures and trigger traffic redirect to the next priority level if the number of healthy endpoints fall below crossZone `failoverThreshold`. When you have a single instance of Zone Egress, all remote zones will be behind a single endpoint. Since `MeshCircuitBreaker` is configured on Data Plane Proxy, when one of the zones start responding with errors it will mark the whole Zone Egress as not healthy and won’t send traffic there even though there could be multiple zones with live endpoints. From 4135058dfe53d78d97919224919ef0ffbdb5b71d Mon Sep 17 00:00:00 2001 From: Marcin Skalski Date: Mon, 13 Nov 2023 10:30:12 +0100 Subject: [PATCH 12/22] Update app/_src/policies/meshloadbalancingstrategy.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Krzysztof Słonka Signed-off-by: Marcin Skalski --- app/_src/policies/meshloadbalancingstrategy.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/app/_src/policies/meshloadbalancingstrategy.md b/app/_src/policies/meshloadbalancingstrategy.md index 73e188c14..d1d1f3a69 100644 --- a/app/_src/policies/meshloadbalancingstrategy.md +++ b/app/_src/policies/meshloadbalancingstrategy.md @@ -67,7 +67,7 @@ Using Zone Egress Proxy in multizone deployment poses certain limitations for th Moreover, Zone Egress is a simple proxy that uses a long-living L4 connection to Zone Ingress. Consequently, when a new `MeshLoadbalancingStrategy` with locality awareness is configured, connections won’t be refreshed, and locality awareness will apply only to new connections. -Another thing you need to be aware of is that when you use the `MeshCircuitBreaker`'s outlier detection to keep track of healthy endpoints. Normally, you would use `MeshCircuitBreaker` to act on failures and trigger traffic redirect to the next priority level if the number of healthy endpoints fall below crossZone `failoverThreshold`. When you have a single instance of Zone Egress, all remote zones will be behind a single endpoint. Since `MeshCircuitBreaker` is configured on Data Plane Proxy, when one of the zones start responding with errors it will mark the whole Zone Egress as not healthy and won’t send traffic there even though there could be multiple zones with live endpoints. +Another thing you need to be aware of is how outbound traffic behaves when you use the `MeshCircuitBreaker`'s outlier detection to keep track of healthy endpoints. Normally, you would use `MeshCircuitBreaker` to act on failures and trigger traffic redirect to the next priority level if the number of healthy endpoints fall below `crossZone.failoverThreshold`. When you have a single instance of Zone Egress, all remote zones will be behind a single endpoint. Since `MeshCircuitBreaker` is configured on Data Plane Proxy, when one of the zones start responding with errors it will mark the whole Zone Egress as not healthy and won’t send traffic there even though there could be multiple zones with live endpoints. {% endif_version %} From 2228a22ed1ad7ba4ac37642ef493cb5d9c265e3d Mon Sep 17 00:00:00 2001 From: Marcin Skalski Date: Mon, 13 Nov 2023 10:31:39 +0100 Subject: [PATCH 13/22] Update meshloadbalancingstrategy.md --- app/_src/policies/meshloadbalancingstrategy.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/app/_src/policies/meshloadbalancingstrategy.md b/app/_src/policies/meshloadbalancingstrategy.md index d1d1f3a69..d8d2c36e7 100644 --- a/app/_src/policies/meshloadbalancingstrategy.md +++ b/app/_src/policies/meshloadbalancingstrategy.md @@ -67,7 +67,7 @@ Using Zone Egress Proxy in multizone deployment poses certain limitations for th Moreover, Zone Egress is a simple proxy that uses a long-living L4 connection to Zone Ingress. Consequently, when a new `MeshLoadbalancingStrategy` with locality awareness is configured, connections won’t be refreshed, and locality awareness will apply only to new connections. -Another thing you need to be aware of is how outbound traffic behaves when you use the `MeshCircuitBreaker`'s outlier detection to keep track of healthy endpoints. Normally, you would use `MeshCircuitBreaker` to act on failures and trigger traffic redirect to the next priority level if the number of healthy endpoints fall below `crossZone.failoverThreshold`. When you have a single instance of Zone Egress, all remote zones will be behind a single endpoint. Since `MeshCircuitBreaker` is configured on Data Plane Proxy, when one of the zones start responding with errors it will mark the whole Zone Egress as not healthy and won’t send traffic there even though there could be multiple zones with live endpoints. +Another thing you need to be aware of is how outbound traffic behaves when you use the `MeshCircuitBreaker`'s outlier detection to keep track of healthy endpoints. Normally, you would use `MeshCircuitBreaker` to act on failures and trigger traffic redirect to the next priority level if the number of healthy endpoints fall below `crossZone.failoverThreshold`. When you have a single instance of Zone Egress, all remote zones will be behind a single endpoint. Since `MeshCircuitBreaker` is configured on Data Plane Proxy, when one of the zones start responding with errors it will mark the whole Zone Egress as not healthy and won’t send traffic there even though there could be multiple zones with live endpoints. This will be changed in ther future with overall improvements to the Zone Egress proxy. {% endif_version %} From c866e430b40121a9c7c1b739aca425e476f7019e Mon Sep 17 00:00:00 2001 From: Marcin Skalski Date: Mon, 13 Nov 2023 12:57:53 +0100 Subject: [PATCH 14/22] Update app/_src/policies/meshloadbalancingstrategy.md Co-authored-by: Charly Molter Signed-off-by: Marcin Skalski --- app/_src/policies/meshloadbalancingstrategy.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/app/_src/policies/meshloadbalancingstrategy.md b/app/_src/policies/meshloadbalancingstrategy.md index d8d2c36e7..6292506e1 100644 --- a/app/_src/policies/meshloadbalancingstrategy.md +++ b/app/_src/policies/meshloadbalancingstrategy.md @@ -63,7 +63,7 @@ Advanced locality-aware load balancing provides a powerful means of defining how #### Zone Egress support -Using Zone Egress Proxy in multizone deployment poses certain limitations for this policy. When configuring `MeshLoadbalancingStrategy` with Zone Egress you can only use `Mesh` as a top level targetRef. This is because we don't differentiate requests that come to Zone Egress from different clients, yet. +Using Zone Egress Proxy in multizone deployment poses certain limitations for this feature. When configuring `MeshLoadbalancingStrategy` with Zone Egress you can only use `Mesh` as a top level targetRef. This is because we don't differentiate requests that come to Zone Egress from different clients, yet. Moreover, Zone Egress is a simple proxy that uses a long-living L4 connection to Zone Ingress. Consequently, when a new `MeshLoadbalancingStrategy` with locality awareness is configured, connections won’t be refreshed, and locality awareness will apply only to new connections. From 17922a1aa00b983cf95a3e93f92709465e40c62d Mon Sep 17 00:00:00 2001 From: Marcin Skalski Date: Mon, 13 Nov 2023 12:58:14 +0100 Subject: [PATCH 15/22] Update app/_src/policies/meshloadbalancingstrategy.md Co-authored-by: Charly Molter Signed-off-by: Marcin Skalski --- app/_src/policies/meshloadbalancingstrategy.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/app/_src/policies/meshloadbalancingstrategy.md b/app/_src/policies/meshloadbalancingstrategy.md index 6292506e1..000a28a63 100644 --- a/app/_src/policies/meshloadbalancingstrategy.md +++ b/app/_src/policies/meshloadbalancingstrategy.md @@ -65,7 +65,7 @@ Advanced locality-aware load balancing provides a powerful means of defining how Using Zone Egress Proxy in multizone deployment poses certain limitations for this feature. When configuring `MeshLoadbalancingStrategy` with Zone Egress you can only use `Mesh` as a top level targetRef. This is because we don't differentiate requests that come to Zone Egress from different clients, yet. -Moreover, Zone Egress is a simple proxy that uses a long-living L4 connection to Zone Ingress. Consequently, when a new `MeshLoadbalancingStrategy` with locality awareness is configured, connections won’t be refreshed, and locality awareness will apply only to new connections. +Moreover, Zone Egress is a simple proxy that uses long-lived L4 connection with each Zone Ingresses. Consequently, when a new `MeshLoadbalancingStrategy` with locality awareness is configured, connections won’t be refreshed, and locality awareness will apply only to new connections. Another thing you need to be aware of is how outbound traffic behaves when you use the `MeshCircuitBreaker`'s outlier detection to keep track of healthy endpoints. Normally, you would use `MeshCircuitBreaker` to act on failures and trigger traffic redirect to the next priority level if the number of healthy endpoints fall below `crossZone.failoverThreshold`. When you have a single instance of Zone Egress, all remote zones will be behind a single endpoint. Since `MeshCircuitBreaker` is configured on Data Plane Proxy, when one of the zones start responding with errors it will mark the whole Zone Egress as not healthy and won’t send traffic there even though there could be multiple zones with live endpoints. This will be changed in ther future with overall improvements to the Zone Egress proxy. From 64b3385dccbd112e84cf91b0e82afc083877cdb0 Mon Sep 17 00:00:00 2001 From: Lukasz Dziedziak Date: Mon, 13 Nov 2023 13:04:55 +0100 Subject: [PATCH 16/22] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Charly Molter Co-authored-by: Krzysztof Słonka Signed-off-by: Lukasz Dziedziak --- app/_src/policies/meshloadbalancingstrategy.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/app/_src/policies/meshloadbalancingstrategy.md b/app/_src/policies/meshloadbalancingstrategy.md index 000a28a63..bdb936d15 100644 --- a/app/_src/policies/meshloadbalancingstrategy.md +++ b/app/_src/policies/meshloadbalancingstrategy.md @@ -35,30 +35,30 @@ across all endpoints regardless of locality. Advanced locality-aware load balancing provides a more robust and straightforward method for balancing traffic within and across zones. This not only allows you to route traffic across zones when the local zone service is unhealthy but also enables you to define traffic prioritization within the local zone and set cross-zone fallback priorities. #### LocalZone -Local zone routing allows you to define traffic routing rules within a local zone, prioritizing data planes based on tags and their associated weights. This enables you to allocate specific traffic percentages to data planes with particular tags within the local zone. If there are no healthy endpoints within the highest priority group, the next priority group takes precedence. Locality awareness within the local zone relies on tags within inbounds, so it's crucial to ensure that the tags used in the policy are defined for the service (Dataplane object on Universal, Deployment annotations on Kubernetes). +Local zone routing allows you to define traffic routing rules within a local zone, prioritizing data planes based on tags and their associated weights. This enables you to allocate specific traffic percentages to data planes with particular tags within the local zone. If there are no healthy endpoints within the highest priority group, the next priority group takes precedence. Locality awareness within the local zone relies on tags within inbounds, so it's crucial to ensure that the tags used in the policy are defined for the service (Dataplane object on Universal, PodTemplate labels on Kubernetes). - **`localZone`** - (optional) allows to define load balancing priorities between dataplanes in the local zone. When not defined, traffic is distributed equally to all endpoints within the local zone. - **`affinityTags`** - list of tags and their weights based on which traffic is load balanced - - **`key`** - defines tag for which affinity is configured. The tag needs to be configured on the inbound of the service. In case of Kubernetes, pod needs to have an annotations or a label. On Universal user needs to define it on the inbound of the service. In case there no match, the dataplane match to the last group with the lowest weight. + - **`key`** - defines tag for which affinity is configured. The tag needs to be configured on the inbound of the service. In case of Kubernetes, pod needs to have an annotations or a label. On Universal user needs to define it on the inbound of the service. In case there is no match, the dataplane match to the last group with the lowest weight. - **`weight`** - (optional) weight of the tag used for load balancing. The bigger the weight the higher number of requests is routed to dataplanes with specific tag. By default we will adjust them so that 90% traffic goes to first tag, 9% to next, and 1% to third and so on. #### CrossZone {% warning %} -Remember that cross-zone traffic requires [mTLS enabled](/docs/{{ page.version}}/policies/mutual-tls). +Remember that cross-zone traffic requires [mTLS to be enabled](/docs/{{ page.version}}/policies/mutual-tls). {% endwarning %} -Advanced locality-aware load balancing provides a powerful means of defining how your service should behave when there is no service available in your local zone. With this feature, you have the flexibility to configure the fallback behavior of your service, specifying the order in which it should attempt fallback options and defining different behaviors for instances located in various zones. +Advanced locality-aware load balancing provides a powerful means of defining how your service should behave when there is no instances of your service available or they are in a degraded state in your local zone. With this feature, you have the flexibility to configure the fallback behavior of your service, specifying the order in which it should attempt fallback options and defining different behaviors for instances located in various zones. - **`crossZone`** - (optional) allows to define behaviour when there is no healthy instances of the service. When not defined, cross zone traffic is disabled. - **`failover`** - defines a list of load balancing rules in order of priority. If a zone is not specified explicitly by name or implicitly using the type `Any`/`AnyExcept` it is excluded from receiving traffic. By default, the last rule is always `None` which means, that there is no traffic to other zones after specified rules. - **`from`** - (optional) defines the list of zones to which the rule applies. If not specified, rule is applied to all zones. - - **`zones`** - list of zones. + - **`zones`** - list of zone names. - **`to`** - defines to which zones the traffic should be load balanced. - **`type`** - defines how target zones will be picked from available zones. Available options: - **`Any`** - traffic will be load balanced to every available zone. - **`Only`** - traffic will be load balanced only to zones specified in zones list. - - **`AnyExcept`** - traffic will be load balanced to every available zone except these specified in zones list. + - **`AnyExcept`** - traffic will be load balanced to every available zone except those specified in zones list. - **`None`** - traffic will not be load balanced to any zone. - - **`zones`** - names of zones + - **`zones`** - list of zone names - **`failoverThreshold.percentage`** - (optional) defines the percentage of live destination dataplane proxies below which load balancing to the next priority starts. Default: 50% #### Zone Egress support From 23fe1192eb7d2d4139588505d064445e5f8d8cfc Mon Sep 17 00:00:00 2001 From: Lukasz Dziedziak Date: Mon, 13 Nov 2023 14:41:37 +0100 Subject: [PATCH 17/22] Apply suggestions from code review Co-authored-by: Charly Molter Signed-off-by: Lukasz Dziedziak --- app/_src/policies/meshloadbalancingstrategy.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/app/_src/policies/meshloadbalancingstrategy.md b/app/_src/policies/meshloadbalancingstrategy.md index bdb936d15..7f2731f33 100644 --- a/app/_src/policies/meshloadbalancingstrategy.md +++ b/app/_src/policies/meshloadbalancingstrategy.md @@ -39,7 +39,7 @@ Local zone routing allows you to define traffic routing rules within a local zon - **`localZone`** - (optional) allows to define load balancing priorities between dataplanes in the local zone. When not defined, traffic is distributed equally to all endpoints within the local zone. - **`affinityTags`** - list of tags and their weights based on which traffic is load balanced - - **`key`** - defines tag for which affinity is configured. The tag needs to be configured on the inbound of the service. In case of Kubernetes, pod needs to have an annotations or a label. On Universal user needs to define it on the inbound of the service. In case there is no match, the dataplane match to the last group with the lowest weight. + - **`key`** - defines tag for which affinity is configured. The tag needs to be configured on the inbound of the service. In case of Kubernetes, pod needs to have a label. On Universal user needs to define it on the inbound of the service. If the tag is absent this entry is skipped. - **`weight`** - (optional) weight of the tag used for load balancing. The bigger the weight the higher number of requests is routed to dataplanes with specific tag. By default we will adjust them so that 90% traffic goes to first tag, 9% to next, and 1% to third and so on. #### CrossZone From dd827ed3f39c1c8f9a6f4cf2f53588b653a3d0a1 Mon Sep 17 00:00:00 2001 From: Lukasz Dziedziak Date: Mon, 13 Nov 2023 14:54:09 +0100 Subject: [PATCH 18/22] refactor Signed-off-by: Lukasz Dziedziak --- app/_src/policies/locality-aware.md | 6 ++++++ .../policies/meshloadbalancingstrategy.md | 19 ++++++++++++++----- 2 files changed, 20 insertions(+), 5 deletions(-) diff --git a/app/_src/policies/locality-aware.md b/app/_src/policies/locality-aware.md index 295088b57..d831d6dc8 100644 --- a/app/_src/policies/locality-aware.md +++ b/app/_src/policies/locality-aware.md @@ -2,6 +2,12 @@ title: Locality-aware Load Balancing --- +{% if_version gte:2.5.x %} +{% warning %} +If you are looking for more advanced configuration use [MeshLoadBalancingStrategy](/docs/{{ page.version }}/policies/meshloadbalancingstrategy). +{% endwarning %} +{% endif_version %} + In a {% if_version lte:2.1.x %}[multi-zone deployment](/docs/{{ page.version }}/introduction/deployments/){% endif_version %}{% if_version gte:2.2.x %}[multi-zone deployment](/docs/{{ page.version }}/production/deployment/){% endif_version %}, locality-aware load balancing instructs data plane proxies to try to keep requests within one zone. The amount of traffic that remains in one zone depends on the health of the service endpoints in that diff --git a/app/_src/policies/meshloadbalancingstrategy.md b/app/_src/policies/meshloadbalancingstrategy.md index 7f2731f33..996c794bf 100644 --- a/app/_src/policies/meshloadbalancingstrategy.md +++ b/app/_src/policies/meshloadbalancingstrategy.md @@ -23,6 +23,7 @@ To learn more about the information in this table, see the [matching docs](/docs ## Configuration +{% if_version lte:2.4.x %} ### LocalityAwareness Locality-aware load balancing is enabled by default unlike its predecessor [localityAwareLoadBalancing](/docs/{{ page.version }}/policies/locality-aware). @@ -30,11 +31,20 @@ Locality-aware load balancing is enabled by default unlike its predecessor [loca - **`disabled`** – (optional) allows to disable locality-aware load balancing. When disabled requests are distributed across all endpoints regardless of locality. +{% endif_version %} {% if_version gte:2.5.x %} -### Advanced LocalityAwareness -Advanced locality-aware load balancing provides a more robust and straightforward method for balancing traffic within and across zones. This not only allows you to route traffic across zones when the local zone service is unhealthy but also enables you to define traffic prioritization within the local zone and set cross-zone fallback priorities. +### LocalityAwareness +Locality-aware load balancing provides a more robust and straightforward method for balancing traffic within and across zones. This not only allows you to route traffic across zones when the local zone service is unhealthy but also enables you to define traffic prioritization within the local zone and set cross-zone fallback priorities. + +#### Default behaviour +Locality-aware load balancing is enabled by default, unlike its predecessor [localityAwareLoadBalancing](/docs/{{ page.version }}/policies/locality-aware). Requests are distributed across all endpoints within the local zone first unless there are not enough healthy endpoints. + +#### Disabling cross zone routing +It's possible to disable cross-zone traffic. In this case, all endpoints are treated equally. + +#### Configuring LocalityAware Load Balancing +- **`disabled`** – (optional) allows to disable locality-aware load balancing. When disabled requests are distributed across all endpoints regardless of locality. -#### LocalZone Local zone routing allows you to define traffic routing rules within a local zone, prioritizing data planes based on tags and their associated weights. This enables you to allocate specific traffic percentages to data planes with particular tags within the local zone. If there are no healthy endpoints within the highest priority group, the next priority group takes precedence. Locality awareness within the local zone relies on tags within inbounds, so it's crucial to ensure that the tags used in the policy are defined for the service (Dataplane object on Universal, PodTemplate labels on Kubernetes). - **`localZone`** - (optional) allows to define load balancing priorities between dataplanes in the local zone. When not defined, traffic is distributed equally to all endpoints within the local zone. @@ -42,7 +52,6 @@ Local zone routing allows you to define traffic routing rules within a local zon - **`key`** - defines tag for which affinity is configured. The tag needs to be configured on the inbound of the service. In case of Kubernetes, pod needs to have a label. On Universal user needs to define it on the inbound of the service. If the tag is absent this entry is skipped. - **`weight`** - (optional) weight of the tag used for load balancing. The bigger the weight the higher number of requests is routed to dataplanes with specific tag. By default we will adjust them so that 90% traffic goes to first tag, 9% to next, and 1% to third and so on. -#### CrossZone {% warning %} Remember that cross-zone traffic requires [mTLS to be enabled](/docs/{{ page.version}}/policies/mutual-tls). {% endwarning %} @@ -306,7 +315,7 @@ spec: ### Disable cross zone traffic and route to the local zone instances equally -In this example, when a user sends a request to the backend service, the request is routed equally to all instances in the local zone. If there are no instances in the local zone, the request will fail because there is no cross-zone traffic. +In this example, when a user sends a request to the backend service, the request is routed equally to all instances in the local zone. If there are no instances in the local zone, the request will fail because there is no cross zone traffic. {% policy_yaml local-zone-affinity-backend-2 %} ```yaml From c42ac0321d34926856a8d4081aebb2e3979477ec Mon Sep 17 00:00:00 2001 From: Lukasz Dziedziak Date: Mon, 13 Nov 2023 14:56:43 +0100 Subject: [PATCH 19/22] fix percentage description Signed-off-by: Lukasz Dziedziak --- app/_src/policies/meshloadbalancingstrategy.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/app/_src/policies/meshloadbalancingstrategy.md b/app/_src/policies/meshloadbalancingstrategy.md index 996c794bf..4a5e32298 100644 --- a/app/_src/policies/meshloadbalancingstrategy.md +++ b/app/_src/policies/meshloadbalancingstrategy.md @@ -68,7 +68,7 @@ Advanced locality-aware load balancing provides a powerful means of defining how - **`AnyExcept`** - traffic will be load balanced to every available zone except those specified in zones list. - **`None`** - traffic will not be load balanced to any zone. - **`zones`** - list of zone names - - **`failoverThreshold.percentage`** - (optional) defines the percentage of live destination dataplane proxies below which load balancing to the next priority starts. Default: 50% + - **`failoverThreshold.percentage`** - (optional) defines the percentage of live destination dataplane proxies below which load balancing to the next priority starts. Has to be in (0.0 - 100.0] range. If the value is a double number, put it in quotes. #### Zone Egress support From 78916e55a771a3398612e88bfc8789997bf215d1 Mon Sep 17 00:00:00 2001 From: Lukasz Dziedziak Date: Mon, 13 Nov 2023 15:25:09 +0100 Subject: [PATCH 20/22] added note about disabled Signed-off-by: Lukasz Dziedziak --- app/_src/policies/meshloadbalancingstrategy.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/app/_src/policies/meshloadbalancingstrategy.md b/app/_src/policies/meshloadbalancingstrategy.md index 4a5e32298..74a76cd88 100644 --- a/app/_src/policies/meshloadbalancingstrategy.md +++ b/app/_src/policies/meshloadbalancingstrategy.md @@ -45,6 +45,10 @@ It's possible to disable cross-zone traffic. In this case, all endpoints are tre #### Configuring LocalityAware Load Balancing - **`disabled`** – (optional) allows to disable locality-aware load balancing. When disabled requests are distributed across all endpoints regardless of locality. +{% warning %} +If `crossZone` and/or `localZone` is defined, they take precedence over `disabled` and apply more specific configuration. +{% endwarning %} + Local zone routing allows you to define traffic routing rules within a local zone, prioritizing data planes based on tags and their associated weights. This enables you to allocate specific traffic percentages to data planes with particular tags within the local zone. If there are no healthy endpoints within the highest priority group, the next priority group takes precedence. Locality awareness within the local zone relies on tags within inbounds, so it's crucial to ensure that the tags used in the policy are defined for the service (Dataplane object on Universal, PodTemplate labels on Kubernetes). - **`localZone`** - (optional) allows to define load balancing priorities between dataplanes in the local zone. When not defined, traffic is distributed equally to all endpoints within the local zone. From 7b2a29948aadb9c9e58ae88b402e5dfef9615aa1 Mon Sep 17 00:00:00 2001 From: Lukasz Dziedziak Date: Mon, 13 Nov 2023 15:54:58 +0100 Subject: [PATCH 21/22] refactor and review Signed-off-by: Lukasz Dziedziak --- app/_src/policies/locality-aware.md | 2 +- app/_src/policies/meshloadbalancingstrategy.md | 14 +++++++++----- 2 files changed, 10 insertions(+), 6 deletions(-) diff --git a/app/_src/policies/locality-aware.md b/app/_src/policies/locality-aware.md index d831d6dc8..8ae13a3fe 100644 --- a/app/_src/policies/locality-aware.md +++ b/app/_src/policies/locality-aware.md @@ -4,7 +4,7 @@ title: Locality-aware Load Balancing {% if_version gte:2.5.x %} {% warning %} -If you are looking for more advanced configuration use [MeshLoadBalancingStrategy](/docs/{{ page.version }}/policies/meshloadbalancingstrategy). +This mode of doing locality aware load balancing is being replaced by [MeshLoadBalancingStrategy](/docs/{{ page.version }}/policies/meshloadbalancingstrategy) which is more powerful and flexible. {% endwarning %} {% endif_version %} diff --git a/app/_src/policies/meshloadbalancingstrategy.md b/app/_src/policies/meshloadbalancingstrategy.md index 74a76cd88..a040ddea9 100644 --- a/app/_src/policies/meshloadbalancingstrategy.md +++ b/app/_src/policies/meshloadbalancingstrategy.md @@ -34,17 +34,20 @@ across all endpoints regardless of locality. {% endif_version %} {% if_version gte:2.5.x %} ### LocalityAwareness -Locality-aware load balancing provides a more robust and straightforward method for balancing traffic within and across zones. This not only allows you to route traffic across zones when the local zone service is unhealthy but also enables you to define traffic prioritization within the local zone and set cross-zone fallback priorities. +Locality-aware load balancing provides robust and straightforward method for balancing traffic within and across zones. This not only allows you to route traffic across zones when the local zone service is unhealthy but also enables you to define traffic prioritization within the local zone and set cross-zone fallback priorities. #### Default behaviour Locality-aware load balancing is enabled by default, unlike its predecessor [localityAwareLoadBalancing](/docs/{{ page.version }}/policies/locality-aware). Requests are distributed across all endpoints within the local zone first unless there are not enough healthy endpoints. -#### Disabling cross zone routing -It's possible to disable cross-zone traffic. In this case, all endpoints are treated equally. +#### Disabling locality aware routing +If you do so, all endpoints regardless of their zone will be treated equally. To do this do: -#### Configuring LocalityAware Load Balancing -- **`disabled`** – (optional) allows to disable locality-aware load balancing. When disabled requests are distributed across all endpoints regardless of locality. +```yaml +localityAwareness: + disabled: true +``` +#### Configuring LocalityAware Load Balancing for traffic within the same zone {% warning %} If `crossZone` and/or `localZone` is defined, they take precedence over `disabled` and apply more specific configuration. {% endwarning %} @@ -56,6 +59,7 @@ Local zone routing allows you to define traffic routing rules within a local zon - **`key`** - defines tag for which affinity is configured. The tag needs to be configured on the inbound of the service. In case of Kubernetes, pod needs to have a label. On Universal user needs to define it on the inbound of the service. If the tag is absent this entry is skipped. - **`weight`** - (optional) weight of the tag used for load balancing. The bigger the weight the higher number of requests is routed to dataplanes with specific tag. By default we will adjust them so that 90% traffic goes to first tag, 9% to next, and 1% to third and so on. +#### Configuring LocalityAware Load Balancing for traffic across zones {% warning %} Remember that cross-zone traffic requires [mTLS to be enabled](/docs/{{ page.version}}/policies/mutual-tls). {% endwarning %} From 11473adcec88e852a80bf89a873932f43cde1e42 Mon Sep 17 00:00:00 2001 From: Lukasz Dziedziak Date: Tue, 14 Nov 2023 14:59:50 +0100 Subject: [PATCH 22/22] fix typo Signed-off-by: Lukasz Dziedziak --- app/_src/policies/meshloadbalancingstrategy.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/app/_src/policies/meshloadbalancingstrategy.md b/app/_src/policies/meshloadbalancingstrategy.md index a040ddea9..276353549 100644 --- a/app/_src/policies/meshloadbalancingstrategy.md +++ b/app/_src/policies/meshloadbalancingstrategy.md @@ -84,7 +84,7 @@ Using Zone Egress Proxy in multizone deployment poses certain limitations for th Moreover, Zone Egress is a simple proxy that uses long-lived L4 connection with each Zone Ingresses. Consequently, when a new `MeshLoadbalancingStrategy` with locality awareness is configured, connections won’t be refreshed, and locality awareness will apply only to new connections. -Another thing you need to be aware of is how outbound traffic behaves when you use the `MeshCircuitBreaker`'s outlier detection to keep track of healthy endpoints. Normally, you would use `MeshCircuitBreaker` to act on failures and trigger traffic redirect to the next priority level if the number of healthy endpoints fall below `crossZone.failoverThreshold`. When you have a single instance of Zone Egress, all remote zones will be behind a single endpoint. Since `MeshCircuitBreaker` is configured on Data Plane Proxy, when one of the zones start responding with errors it will mark the whole Zone Egress as not healthy and won’t send traffic there even though there could be multiple zones with live endpoints. This will be changed in ther future with overall improvements to the Zone Egress proxy. +Another thing you need to be aware of is how outbound traffic behaves when you use the `MeshCircuitBreaker`'s outlier detection to keep track of healthy endpoints. Normally, you would use `MeshCircuitBreaker` to act on failures and trigger traffic redirect to the next priority level if the number of healthy endpoints fall below `crossZone.failoverThreshold`. When you have a single instance of Zone Egress, all remote zones will be behind a single endpoint. Since `MeshCircuitBreaker` is configured on Data Plane Proxy, when one of the zones start responding with errors it will mark the whole Zone Egress as not healthy and won’t send traffic there even though there could be multiple zones with live endpoints. This will be changed in the future with overall improvements to the Zone Egress proxy. {% endif_version %}