Locality LB failover api

mesh/v1alpha1/config.proto

@@ -195,6 +195,9 @@ message MeshConfig {
   // can be configured for a single control plane.
   repeated ConfigSource config_sources = 22;
 
+  // Locality based load balancing distribution or failover settings.
+  LocalityLoadBalancerSetting locality_lb_setting = 31;
+
   // $hide_from_docs
   // This flag is used by secret discovery service(SDS).
   // If set to true(prerequisite: https://kubernetes.io/docs/concepts/storage/volumes/#projected), Istio will inject volumes mount
@@ -218,7 +221,7 @@ message MeshConfig {
   string trust_domain = 26;
 
   // $hide_from_docs
-  // Next available field number: 31
+  // Next available field number: 32
 }
 
 // ConfigSource describes information about a configuration store inside a
@@ -235,3 +238,70 @@ message ConfigSource {
   // mode as ISTIO_MUTUAL.
   istio.networking.v1alpha3.TLSSettings tls_settings = 2;
 }
+
+
+// The following example sets up locality weight for mesh wide service
+// Assume a service resides in "region1/zone1/*" and "region1/zone2/*",
+// and originating clusters also reside in "region1/zone1/*" and "region1/zone2/*".
+// This example specifies when clusters from "region1/zone1/*" accessing the service, 80% of the traffic
+// is shipped to "region1/zone1/*" ratings service endpoints, and the rest 20% to "region1/zone2/*".
+//
+// ```yaml
+//   distribute:
+//     - from: region1/zone1/*
+//       to:
+//         "region1/zone1/*": 80
+//         "region1/zone2/*": 20
+//     - from: region1/zone2/*
+//       to:
+//         "region1/zone1/*": 20
+//         "region1/zone2/*": 80
+// ```
+//
+// The following example sets up locality failover policy for the ratings service
+// Assume a service resides in "region1" "region2" and "region3",
+// This example specifies when clusters from "region1/zone1" accessing the service,
+// if endpoints in "region1" becomes unhealthy, traffic will begin to trickle to "region2".
+//
+// ```yaml
+//  failover:
+//    - from: region1
+//      to: region2
+// ```
+// Locality load balancing settings.
+message LocalityLoadBalancerSetting{
+  // Originating -> upstream cluster locality weight set, support wildcard matching '*'
+  // '*' matches all localities
+  // 'region1/*' matches all zones in region1
+  message Distribute{
+      // Originating locality, '/' separated, e.g. 'region/zone/sub_zone'.
+      string from = 1;
+
+      // Upstream locality to loadbalancing weight map. The sum of all weights should be == 100.
+      // Should assign load balancing weight for all localities, otherwise the traffic are not routed
+      // following the percentage of weight.
+      map<string, uint32> to = 2;
+  };
+
+  // Specify the traffic failover policy.
+  // As zone and sub_zone failover is supported by default, only region can be specified here.
+  message Failover{
+      // Originating region.
+      string from = 1;
+
+      // Destination region the traffic will fail over to when endpoints in local region becomes unhealthy.
+      string to = 2;
+  };
+
+  // Optional: only distribute or failover can be set.
+  // Explicitly specify loadbalancing weight across different zones and geographical locations.
+  // Refer to [Locality weighted load balancing](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/load_balancing.html?highlight=load_balancing_weight#locality-weighted-load-balancing)
+  // If empty, the locality weight is set according to the endpoints number within it.
+  repeated Distribute distribute = 1;
+
+  // Optional: only failover or distribute can be set.
+  // Explicitly specify the region traffic will land on when endpoints in local region becomes unhealthy.
+  // Should be used together with OutlierDetection to detect unhealthy endpoints.
+  // Note: if no OutlierDetection specified, this will not take effect.
+  repeated Failover failover = 2;
+}