feat(mlbs): create first draft

Signed-off-by: Lukasz Dziedziak <[email protected]>

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 %}