Locality Load Balancing

A locality defines a geographic location within your mesh using the following triplet:

• Region
• Zone
• Sub-zone

The geographic location typically represents a data center. Istio usesthis information to prioritize load balancing pools to controlthe geographic location where requests are sent.

Configuring locality load balancing

This feature is enabled by default. To disable locality load balancing,pass the —set global.localityLbSetting.enabled=false flag when installing Istio.

Requirements

Currently, the service discovery platform populates the locality automatically.In Kubernetes, a pod’s locality is determined via the well-known labels for region and zoneon the node it is deployed. If you are using a hosted Kubernetes service your cloud providershould configure this for you. If you are running your own Kubernetes cluster you will needto add these labels to your nodes. The sub-zone concept doesn’t exist in Kubernetes.As a result, this field does not need to be configured.

In order for Istio to determine locality, a Service must be associated with the caller.

To determine when instances are unhealthy, the proxies require an outlier detectionconfiguration in a destination rule for each service.

Locality-prioritized load balancing

Locality-prioritized load balancing is the default behavior for locality load balancing.In this mode, Istio tells Envoy to prioritize traffic to the workload instances most closely matchingthe locality of the Envoy sending the request. When all instances are healthy, the requestsremains within the same locality. When instances become unhealthy, traffic spills over toinstances in the next prioritized locality. This behavior continues until all localities arereceiving traffic. You can find the exact percentages in the Envoy documentation.

If no outlier detection configurations are defined in destination rules, the proxy can’t determine if an instance is healthy, and itroutes traffic globally even if you enabled locality-prioritized load balancing.

A typical prioritization for an Envoy with a locality of us-west/zone2 is as follows:

• Priority 0: us-west/zone2
• Priority 1: us-west/zone1, us-west/zone3
• Priority 2: us-east/zone1, us-east/zone2, eu-west/zone1

The hierarchy of prioritization matches in the following order:

• Region
• Zone
• Sub-zoneProxies in the same zone but different regions are not considered local to one another.

Overriding the locality fail-over

Sometimes, you need to constrain the traffic fail-over to avoid sending traffic toendpoints across the globe when there are not enough healthy endpoints in thesame region. This behavior is useful when sending fail-over traffic across regionswould not improve service health or many other reasons including regulatory controls.To constrain traffic to a region, configure the values.localityLbSetting option during install. See theLocality load balancing reference guidefor options.

An example configuration:

global:
  localityLbSetting:
    enabled: true
    failover:
    - from: us-east
      to: eu-west
    - from: us-west
      to: us-east

Locality-weighted load balancing

Locality-weighted load balancing distributes user-defined percentages of traffic to certain localities.

For example, if we want to keep 80% of traffic within our region, and send 20% of traffic out of region:

global:
  localityLbSetting:
    enabled: true
    distribute:
    - from: "us-central1/*"
      to:
        "us-central1/*": 80
        "us-central2/*": 20