Add locality load balancing docs to traffic management concepts (#3593)

* Add locality load balancing docs to traffic management concepts

Signed-off-by: Liam White <liam@tetrate.io>

* appease our linting overlords

Signed-off-by: Liam White <liam@tetrate.io>

* Update content/docs/concepts/traffic-management/index.md

Co-Authored-By: liamawhite <liamawhite@gmail.com>

* Apply suggestions from code review

Co-Authored-By: liamawhite <liamawhite@gmail.com>

* clean up the mess I made with gh suggestions

Signed-off-by: Liam White <liam@tetrate.io>

* Move the docs around to ops guide

Signed-off-by: Liam White <liam@tetrate.io>

* Correct hierarchy ordering

Signed-off-by: Liam White <liam@tetrate.io>

* remove errant slash

Signed-off-by: Liam White <liam@tetrate.io>

* s/service/workload/g

Signed-off-by: Liam White <liam@tetrate.io>

* 🤦

Signed-off-by: Liam White <liam@tetrate.io>

* fix numberings

Signed-off-by: Liam White <liam@tetrate.io>

.spelling

@@ -152,6 +152,7 @@ ExecAction
 Exfiltrating
 ExternalName
 facto
+failover
 failovers
 faq
 faq.md

content/docs/concepts/traffic-management/index.md

@@ -194,6 +194,20 @@ Services can actively shed load by responding with an HTTP 503 to a health
 check. In such an event, the service instance will be immediately removed
 from the caller's load balancing pool.
 
+### 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 uses
+this information to prioritize load balancing pools to control
+the geographic location where requests are proxied.
+
+For more information and instructions on how to enable this feature see the [operations guide](/help/ops/traffic-management/locality-load-balancing/).
+
 ## Handling failures
 
 Envoy provides a set of out-of-the-box _opt-in_ failure recovery features
@@ -331,15 +345,15 @@ etc.
 There are four traffic management configuration resources in Istio:
 `VirtualService`, `DestinationRule`, `ServiceEntry`, and `Gateway`:
 
-* A [`VirtualService`](/docs/reference/config/networking/v1alpha3/virtual-service/)
+- A [`VirtualService`](/docs/reference/config/networking/v1alpha3/virtual-service/)
 defines the rules that control how requests for a service are routed within an Istio service mesh.
 
-* A [`DestinationRule`](/docs/reference/config/networking/v1alpha3/destination-rule/)
+- A [`DestinationRule`](/docs/reference/config/networking/v1alpha3/destination-rule/)
 configures the set of policies to be applied to a request after `VirtualService` routing has occurred.
 
-* A [`ServiceEntry`](/docs/reference/config/networking/v1alpha3/service-entry/) is commonly used to enable requests to services outside of an Istio service mesh.
+- A [`ServiceEntry`](/docs/reference/config/networking/v1alpha3/service-entry/) is commonly used to enable requests to services outside of an Istio service mesh.
 
-* A [`Gateway`](/docs/reference/config/networking/v1alpha3/gateway/)
+- A [`Gateway`](/docs/reference/config/networking/v1alpha3/gateway/)
 configures a load balancer for HTTP/TCP traffic, most commonly operating at the edge of the mesh to enable ingress traffic for an application.
 
 For example, you can implement a simple rule to send 100% of incoming traffic for a *reviews* service to version "v1" by using a `VirtualService` configuration as follows:

content/help/ops/traffic-management/locality-load-balancing/index.md

@@ -0,0 +1,60 @@
+---
+title: Locality Load Balancing
+description: Information on how to enable and understand Locality Load Balancing.
+weight: 40
+keywords: [locality,load balancing,priority,prioritized]
+---
+
+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 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,
+set the `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](https://kubernetes.io/docs/reference/kubernetes-api/labels-annotations-taints/#failure-domain-beta-kubernetes-io-region)
+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.
+
+## 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](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/load_balancing/priority#priority-levels).
+
+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:
+
+1. Region
+1. Zone
+1. Sub-zone
+
+Proxies 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 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, use the mesh `LocalityLoadBalancerSetting.Failover`
+configuration detailed in the [Locality load balancing reference guide](/docs/reference/config/istio.mesh.v1alpha1/#LocalityLoadBalancerSetting).