MeshLoadBalancingStrategy

This policy uses new policy matching algorithm.

This policy enables Kuma to configure the load balancing strategy for traffic between services in the mesh. When using this policy, the localityAwareLoadBalancing flag is ignored.

TargetRef support matrix

targetRefAllowed kinds
targetRef.kindMesh, MeshSubset, MeshService, MeshServiceSubset
to[].targetRef.kindMesh, MeshService
targetRefAllowed kinds
targetRef.kindMesh, MeshGateway, MeshGateway with listener tags
to[].targetRef.kindMesh, MeshService
targetRefAllowed kinds
targetRef.kindMesh, MeshSubset, MeshService, MeshServiceSubset
to[].targetRef.kindMesh, MeshService

To learn more about the information in this table, see the matching docs.

Configuration

LocalityAwareness

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. Requests are distributed across all endpoints within the local zone first unless there are not enough healthy endpoints.

Disabling locality aware routing

If you do so, all endpoints regardless of their zone will be treated equally. To do this do:

  1. localityAwareness:
  2.   disabled: true

Configuring LocalityAware Load Balancing for traffic within the same zone

If crossZone and/or localZone is defined, they take precedence over disabled and apply more specific configuration.

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

Remember that cross-zone traffic requires mTLS to be enabled.

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 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 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. .e.g: If you have this set to 70 and you have 10 dataplane proxies it will start load balancing to the next priority when the number of healthy destinations falls under 7. The value to be in (0.0 - 100.0] range (Default 50). If the value is a double number, put it in quotes.

Zone Egress support

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 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 the future with overall improvements to the Zone Egress proxy.

LoadBalancer

  • type - available values are RoundRobin, LeastRequest, RingHash, Random, Maglev.

RoundRobin

RoundRobin is a load balancing algorithm that distributes requests across available upstream hosts in round-robin order.

LeastRequest

LeastRequest selects N random available hosts as specified in ‘choiceCount’ (2 by default) and picks the host which has the fewest active requests.

  • choiceCount - (optional) is the number of random healthy hosts from which the host with the fewest active requests will be chosen. Defaults to 2 so that Envoy performs two-choice selection if the field is not set.

RingHash

RingHash implements consistent hashing to upstream hosts. Each host is mapped onto a circle (the “ring”) by hashing its address; each request is then routed to a host by hashing some property of the request, and finding the nearest corresponding host clockwise around the ring.

  • hashFunction - (optional) available values are XX_HASH, MURMUR_HASH_2. Default is XX_HASH.
  • minRingSize - (optional) minimum hash ring size. The larger the ring is (that is, the more hashes there are for each provided host) the better the request distribution will reflect the desired weights. Defaults to 1024 entries, and limited to 8M entries.
  • maxRingSize - (optional) maximum hash ring size. Defaults to 8M entries, and limited to 8M entries, but can be lowered to further constrain resource use.
  • hashPolicies - (optional) specify a list of request/connection properties that are used to calculate a hash. These hash policies are executed in the specified order. If a hash policy has the “terminal” attribute set to true, and there is already a hash generated, the hash is returned immediately, ignoring the rest of the hash policy list.
    • type - available values are Header, Cookie, Connection, QueryParameter, FilterState
    • terminal - is a flag that short-circuits the hash computing. This field provides a ‘fallback’ style of configuration: “if a terminal policy doesn’t work, fallback to rest of the policy list”, it saves time when the terminal policy works. If true, and there is already a hash computed, ignore rest of the list of hash polices.
    • header:
      • name - the name of the request header that will be used to obtain the hash key.
    • cookie:
      • name - the name of the cookie that will be used to obtain the hash key.
      • ttl - (optional) if specified, a cookie with the TTL will be generated if the cookie is not present.
      • path - (optional) the name of the path for the cookie.
    • connection:
      • sourceIP - if true, then hashing is based on a source IP address.
    • queryParameter:
      • name - the name of the URL query parameter that will be used to obtain the hash key. If the parameter is not present, no hash will be produced. Query parameter names are case-sensitive.
    • filterState:
      • key – the name of the Object in the per-request filterState, which is an Envoy::Hashable object. If there is no data associated with the key, or the stored object is not Envoy::Hashable, no hash will be produced.

Random

Random selects a random available host. The random load balancer generally performs better than round-robin if no health checking policy is configured. Random selection avoids bias towards the host in the set that comes after a failed host.

Maglev

Maglev implements consistent hashing to upstream hosts. Maglev can be used as a drop in replacement for the ring hash load balancer any place in which consistent hashing is desired.

  • tableSize - (optional) the table size for Maglev hashing. Maglev aims for “minimal disruption” rather than an absolute guarantee. Minimal disruption means that when the set of upstream hosts change, a connection will likely be sent to the same upstream as it was before. Increasing the table size reduces the amount of disruption. The table size must be prime number limited to 5000011. If it is not specified, the default is 65537.
  • hashPolicies - (optional) specify a list of request/connection properties that are used to calculate a hash. These hash policies are executed in the specified order. If a hash policy has the “terminal” attribute set to true, and there is already a hash generated, the hash is returned immediately, ignoring the rest of the hash policy list.
    • type - available values are Header, Cookie, Connection, QueryParameter, FilterState
    • terminal - is a flag that short-circuits the hash computing. This field provides a ‘fallback’ style of configuration: “if a terminal policy doesn’t work, fallback to rest of the policy list”, it saves time when the terminal policy works. If true, and there is already a hash computed, ignore rest of the list of hash polices.
    • header:
      • name - the name of the request header that will be used to obtain the hash key.
    • cookie:
      • name - the name of the cookie that will be used to obtain the hash key.
      • ttl - (optional) if specified, a cookie with the TTL will be generated if the cookie is not present.
      • path - (optional) the name of the path for the cookie.
    • connection:
      • sourceIP - if true, then hashing is based on a source IP address.
    • queryParameter:
      • name - the name of the URL query parameter that will be used to obtain the hash key. If the parameter is not present, no hash will be produced. Query parameter names are case-sensitive.
    • filterState:
      • key – the name of the Object in the per-request filterState, which is an Envoy::Hashable object. If there is no data associated with the key, or the stored object is not Envoy::Hashable, no hash will be produced.

Examples

RingHash load balancing from web to backend

Load balance requests from web to backend based on the HTTP header x-header:

  1. kind: MeshLoadBalancingStrategy
  2. apiVersion: kuma.io/v1alpha1
  3. metadata:
  4.   name: ring-hash
  5.   namespace: kuma-system
  6.   labels:
  7.     kuma.io/mesh: mesh-1
  8. spec:
  9.   targetRef:
  10.     kind: MeshService
  11.     name: web
  12.   to:
  13.     - targetRef:
  14.         kind: MeshService
  15.         name: backend
  16.       default:
  17.         loadBalancer:
  18.           type: RingHash
  19.           ringHash:
  20.             hashPolicies:
  21.               - type: Header
  22.                 header:
  23.                   name: x-header

Apply the configuration with kubectl apply -f [..].

  1. type: MeshLoadBalancingStrategy
  2. name: ring-hash
  3. mesh: mesh-1
  4. spec:
  5.   targetRef:
  6.     kind: MeshService
  7.     name: web
  8.   to:
  9.     - targetRef:
  10.         kind: MeshService
  11.         name: backend
  12.       default:
  13.         loadBalancer:
  14.           type: RingHash
  15.           ringHash:
  16.             hashPolicies:
  17.               - type: Header
  18.                 header:
  19.                   name: x-header

Apply the configuration with kumactl apply -f [..] or with the HTTP API.

Disable locality-aware load balancing for backend

Requests to backend will be spread evenly across all zones where backend is deployed.

  1. kind: MeshLoadBalancingStrategy
  2. apiVersion: kuma.io/v1alpha1
  3. metadata:
  4.   name: disable-la-to-backend
  5.   namespace: kuma-system
  6.   labels:
  7.     kuma.io/mesh: mesh-1
  8. spec:
  9.   targetRef:
  10.     kind: Mesh
  11.   to:
  12.     - targetRef:
  13.         kind: MeshService
  14.         name: backend
  15.       default:
  16.         localityAwareness:
  17.           disabled: true

Apply the configuration with kubectl apply -f [..].

  1. type: MeshLoadBalancingStrategy
  2. name: disable-la-to-backend
  3. mesh: mesh-1
  4. spec:
  5.   targetRef:
  6.     kind: Mesh
  7.   to:
  8.     - targetRef:
  9.         kind: MeshService
  10.         name: backend
  11.       default:
  12.         localityAwareness:
  13.           disabled: true

Apply the configuration with kumactl apply -f [..] or with the HTTP API.

Disable cross zone traffic and prioritize traffic the dataplanes on the same node and availability zone

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.

  1. apiVersion: kuma.io/v1alpha1
  2. kind: MeshLoadBalancingStrategy
  3. metadata:
  4.   name: local-zone-affinity-backend
  5.   namespace: kuma-system
  6.   labels:
  7.     kuma.io/mesh: mesh-1
  8. spec:
  9.   targetRef:
  10.     kind: Mesh
  11.   to:
  12.   - targetRef:
  13.       kind: MeshService
  14.       name: backend
  15.     default:
  16.       localityAwareness:
  17.         localZone:
  18.           affinityTags:
  19.           - key: k8s.io/node
  20.           - key: k8s.io/az
  1. type: MeshLoadBalancingStrategy
  2. name: local-zone-affinity-backend
  3. mesh: mesh-1
  4. spec:
  5.   targetRef:
  6.     kind: Mesh
  7.   to:
  8.   - targetRef:
  9.       kind: MeshService
  10.       name: backend
  11.     default:
  12.       localityAwareness:
  13.         localZone:
  14.           affinityTags:
  15.           - key: k8s.io/node
  16.           - key: k8s.io/az

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.

  1. apiVersion: kuma.io/v1alpha1
  2. kind: MeshLoadBalancingStrategy
  3. metadata:
  4.   name: local-zone-affinity-backend
  5.   namespace: kuma-system
  6.   labels:
  7.     kuma.io/mesh: mesh-1
  8. spec:
  9.   targetRef:
  10.     kind: Mesh
  11.   to:
  12.   - targetRef:
  13.       kind: MeshService
  14.       name: backend
  15.     default:
  16.       localityAwareness:
  17.         localZone:
  18.           affinityTags: []
  1. type: MeshLoadBalancingStrategy
  2. name: local-zone-affinity-backend
  3. mesh: mesh-1
  4. spec:
  5.   targetRef:
  6.     kind: Mesh
  7.   to:
  8.   - targetRef:
  9.       kind: MeshService
  10.       name: backend
  11.     default:
  12.       localityAwareness:
  13.         localZone:
  14.           affinityTags: []

or

  1. apiVersion: kuma.io/v1alpha1
  2. kind: MeshLoadBalancingStrategy
  3. metadata:
  4.   name: local-zone-affinity-backend
  5.   namespace: kuma-system
  6.   labels:
  7.     kuma.io/mesh: mesh-1
  8. spec:
  9.   targetRef:
  10.     kind: Mesh
  11.   to:
  12.   - targetRef:
  13.       kind: MeshService
  14.       name: backend
  15.     default:
  16.       localityAwareness:
  17.         localZone: {}
  1. type: MeshLoadBalancingStrategy
  2. name: local-zone-affinity-backend
  3. mesh: mesh-1
  4. spec:
  5.   targetRef:
  6.     kind: Mesh
  7.   to:
  8.   - targetRef:
  9.       kind: MeshService
  10.       name: backend
  11.     default:
  12.       localityAwareness:
  13.         localZone: {}

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.

  1. apiVersion: kuma.io/v1alpha1
  2. kind: MeshLoadBalancingStrategy
  3. metadata:
  4.   name: cross-zone-backend
  5.   namespace: kuma-system
  6.   labels:
  7.     kuma.io/mesh: mesh-1
  8. spec:
  9.   targetRef:
  10.     kind: Mesh
  11.   to:
  12.   - targetRef:
  13.       kind: MeshService
  14.       name: backend
  15.     default:
  16.       localityAwareness:
  17.         crossZone:
  18.           failover:
  19.           - to:
  20.               type: Only
  21.               zones:
  22.               - us-1
  23.           - to:
  24.               type: AnyExcept
  25.               zones:
  26.               - us-2
  27.               - us-3
  28.           - to:
  29.               type: Any
  30.           failoverThreshold:
  31.             percentage: 25
  1. type: MeshLoadBalancingStrategy
  2. name: cross-zone-backend
  3. mesh: mesh-1
  4. spec:
  5.   targetRef:
  6.     kind: Mesh
  7.   to:
  8.   - targetRef:
  9.       kind: MeshService
  10.       name: backend
  11.     default:
  12.       localityAwareness:
  13.         crossZone:
  14.           failover:
  15.           - to:
  16.               type: Only
  17.               zones:
  18.               - us-1
  19.           - to:
  20.               type: AnyExcept
  21.               zones:
  22.               - us-2
  23.               - us-3
  24.           - to:
  25.               type: Any
  26.           failoverThreshold:
  27.             percentage: 25

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.099% to data planes in the same region, and the remainder to other local instances.

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.

  1. apiVersion: kuma.io/v1alpha1
  2. kind: MeshLoadBalancingStrategy
  3. metadata:
  4.   name: local-zone-affinity-cross-backend
  5.   namespace: kuma-system
  6.   labels:
  7.     kuma.io/mesh: mesh-1
  8. spec:
  9.   targetRef:
  10.     kind: Mesh
  11.   to:
  12.   - targetRef:
  13.       kind: MeshService
  14.       name: backend
  15.     default:
  16.       localityAwareness:
  17.         localZone:
  18.           affinityTags:
  19.           - key: kubernetes.io/hostname
  20.             weight: 9000
  21.           - key: topology.kubernetes.io/zone
  22.             weight: 9
  23.         crossZone:
  24.           failover:
  25.           - from:
  26.               zones:
  27.               - us-1
  28.               - us-2
  29.               - us-3
  30.             to:
  31.               type: Only
  32.               zones:
  33.               - us-1
  34.               - us-2
  35.               - us-3
  36.           - from:
  37.               zones:
  38.               - eu-1
  39.               - eu-2
  40.               - eu-3
  41.             to:
  42.               type: Only
  43.               zones:
  44.               - eu-1
  45.               - eu-2
  46.               - eu-3
  47.           - to:
  48.               type: Only
  49.               zones:
  50.               - us-4
  1. type: MeshLoadBalancingStrategy
  2. name: local-zone-affinity-cross-backend
  3. mesh: mesh-1
  4. spec:
  5.   targetRef:
  6.     kind: Mesh
  7.   to:
  8.   - targetRef:
  9.       kind: MeshService
  10.       name: backend
  11.     default:
  12.       localityAwareness:
  13.         localZone:
  14.           affinityTags:
  15.           - key: kubernetes.io/hostname
  16.             weight: 9000
  17.           - key: topology.kubernetes.io/zone
  18.             weight: 9
  19.         crossZone:
  20.           failover:
  21.           - from:
  22.               zones:
  23.               - us-1
  24.               - us-2
  25.               - us-3
  26.             to:
  27.               type: Only
  28.               zones:
  29.               - us-1
  30.               - us-2
  31.               - us-3
  32.           - from:
  33.               zones:
  34.               - eu-1
  35.               - eu-2
  36.               - eu-3
  37.             to:
  38.               type: Only
  39.               zones:
  40.               - eu-1
  41.               - eu-2
  42.               - eu-3
  43.           - to:
  44.               type: Only
  45.               zones:
  46.               - us-4

Load balancing HTTP traffic through zone proxies

If you proxy HTTP traffic through zone proxies (zone ingress/egress), you may notice that the traffic does not reach every instance of the destination service. In the case of in-zone traffic (without zone proxies on a request path), the client is aware of all server endpoints, so if you have 10 server endpoints the traffic goes to all of them. In the case of cross-zone traffic, the client is only aware of zone ingress endpoints, so if you have 10 server endpoints and 1 zone ingress, the client only sees one zone ingress endpoint. Because zone ingress is just a TCP passthrough proxy (it does not terminate TLS), it only load balances TCP connections over server endpoints.

HTTP traffic between Envoys is upgraded to HTTP/2 automatically for performance benefits. The client’s Envoy leverages HTTP/2 multiplexing therefore it opens only a few TCP connections.

You can mitigate this problem by adjusting max_requests_per_connection setting on Envoy Cluster. For example

  1. apiVersion: kuma.io/v1alpha1
  2. kind: MeshProxyPatch
  3. metadata:
  4.   name: max-requests-per-conn
  5.   namespace: kuma-system
  6.   labels:
  7.     kuma.io/mesh: mesh-1
  8. spec:
  9.   targetRef:
  10.     kind: Mesh
  11.   default:
  12.     appendModifications:
  13.     - cluster:
  14.         operation: Patch
  15.         match:
  16.           name: demo-app_kuma-demo_svc_5000
  17.           origin: outbound
  18.         value: 'max_requests_per_connection: 1
  20.           '
  1. type: MeshProxyPatch
  2. name: max-requests-per-conn
  3. mesh: mesh-1
  4. spec:
  5.   targetRef:
  6.     kind: Mesh
  7.   default:
  8.     appendModifications:
  9.     - cluster:
  10.         operation: Patch
  11.         match:
  12.           name: demo-app_kuma-demo_svc_5000
  13.           origin: outbound
  14.         value: 'max_requests_per_connection: 1
  16.           '

This way, we allow only one in-flight request on a TCP connection. Consequently, the client will open more TCP connections, leading to fairer load balancing. The downside is that we now have to establish and maintain more TCP connections. Keep this in mind as you adjust the value to suit your needs.

All policy options