Locality Load Balancing
A locality defines a geographic location within your mesh using the following triplet:
The geographic location typically represents a data center. Istio uses this information to prioritize load balancing pools to control the geographic location where requests are sent.
Enabling Locality Load Balancing
This feature is experimental and off by default in 1.1. To enable locality load balancing,
PILOT_ENABLE_LOCALITY_LOAD_BALANCING environment variable in all Pilot instances.
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 zone on the node it is deployed. If you are using a hosted Kubernetes service your cloud provider should configure this for you. If you are running your own Kubernetes cluster you will need to 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.
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 matching the locality of the Envoy sending the request. When all instances are healthy, the requests remains within the same locality. When instances become unhealthy, traffic spills over to instances in the next prioritized locality. This behavior continues until all localities are receiving traffic. You can find the exact percentages in the Envoy documentation.
A typical prioritization for an Envoy with a locality of
us-west/zone2 is as follows:
- Priority 0:
- Priority 1:
- Priority 2:
The hierarchy of prioritization matches in the following order:
Proxies in the same zone but different regions are not considered local to one another.
In order for Envoy to determine when instances are unhealthy, an Outlier Detection rule must be defined for each service.
Overriding the Locality Fail-over
Sometimes, you need to constrain the traffic fail-over to avoid sending traffic to
endpoints across the globe when there are not enough healthy endpoints in the
same region. This behavior is useful when sending fail-over traffic across regions
would not improve service health or many other reasons including regulatory controls.
To constrain traffic to a region, configure the
localityLbSetting option using Helm. See the
Locality load balancing reference guide
An example configuration:
global: localityLbSetting: 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: distribute: - from: "us-central1/*" to: "us-central1/*": 80 "us-central2/*": 20