From 71e6347fa2a7e1e1c860a0a0322e83119b506b1a Mon Sep 17 00:00:00 2001 From: Liam White Date: Thu, 14 Mar 2019 16:42:40 +0000 Subject: [PATCH] Add locality load balancing docs to traffic management concepts (#3593) * Add locality load balancing docs to traffic management concepts Signed-off-by: Liam White * appease our linting overlords Signed-off-by: Liam White * Update content/docs/concepts/traffic-management/index.md Co-Authored-By: liamawhite * Apply suggestions from code review Co-Authored-By: liamawhite * clean up the mess I made with gh suggestions Signed-off-by: Liam White * Move the docs around to ops guide Signed-off-by: Liam White * Correct hierarchy ordering Signed-off-by: Liam White * remove errant slash Signed-off-by: Liam White * s/service/workload/g Signed-off-by: Liam White * :facepalm: Signed-off-by: Liam White * fix numberings Signed-off-by: Liam White --- .spelling | 1 + .../docs/concepts/traffic-management/index.md | 22 +++++-- .../locality-load-balancing/index.md | 60 +++++++++++++++++++ 3 files changed, 79 insertions(+), 4 deletions(-) create mode 100644 content/help/ops/traffic-management/locality-load-balancing/index.md diff --git a/.spelling b/.spelling index 93411b107c..3568e861b5 100644 --- a/.spelling +++ b/.spelling @@ -152,6 +152,7 @@ ExecAction Exfiltrating ExternalName facto +failover failovers faq faq.md diff --git a/content/docs/concepts/traffic-management/index.md b/content/docs/concepts/traffic-management/index.md index d15c50825c..cb3e38848f 100644 --- a/content/docs/concepts/traffic-management/index.md +++ b/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: diff --git a/content/help/ops/traffic-management/locality-load-balancing/index.md b/content/help/ops/traffic-management/locality-load-balancing/index.md new file mode 100644 index 0000000000..505f5ae50e --- /dev/null +++ b/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).