load balancer: added least request/random/round robin load balancer extension

CODEOWNERS

@@ -284,6 +284,11 @@ extensions/filters/http/oauth2 @derekargueta @snowp
 /*/extensions/path/rewrite/uri_template @alyssawilk @yanjunxiang-google
 # Dubbo codec
 /*/extensions/common/dubbo @wbpcode @lizan
+# upstream load balancing policies
+/*/extensions/load_balancing_policies/common @wbpcode @UNOWNED
+/*/extensions/load_balancing_policies/least_request @wbpcode @UNOWNED
+/*/extensions/load_balancing_policies/random @wbpcode @UNOWNED
+/*/extensions/load_balancing_policies/round_robin @wbpcode @UNOWNED
 # Early header mutation
 /*/extensions/http/early_header_mutation/header_mutation @wbpcode @UNOWNED
 

api/envoy/config/cluster/v3/cluster.proto

@@ -1216,6 +1216,7 @@ message LoadBalancingPolicy {
 
     reserved "config", "name", "typed_config";
 
+    // [#extension-category: envoy.load_balancing_policies]
     core.v3.TypedExtensionConfig typed_extension_config = 4;
   }
 

api/envoy/extensions/load_balancing_policies/common/v3/common.proto

@@ -18,7 +18,6 @@ option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/loa
 option (udpa.annotations.file_status).package_version_status = ACTIVE;
 
 // [#protodoc-title: Common configuration for two or more load balancing policy extensions]
-// [#not-implemented-hide:]
 
 message LocalityLbConfig {
   // Configuration for :ref:`zone aware routing

api/envoy/extensions/load_balancing_policies/least_request/v3/least_request.proto

@@ -17,7 +17,7 @@ option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/loa
 option (udpa.annotations.file_status).package_version_status = ACTIVE;
 
 // [#protodoc-title: Least Request Load Balancing Policy]
-// [#not-implemented-hide:]
+// [#extension: envoy.load_balancing_policies.least_request]
 
 // This configuration allows the built-in LEAST_REQUEST LB policy to be configured via the LB policy
 // extension point. See the :ref:`load balancing architecture overview

api/envoy/extensions/load_balancing_policies/random/v3/random.proto

@@ -13,7 +13,7 @@ option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/loa
 option (udpa.annotations.file_status).package_version_status = ACTIVE;
 
 // [#protodoc-title: Random Load Balancing Policy]
-// [#not-implemented-hide:]
+// [#extension: envoy.load_balancing_policies.random]
 
 // This configuration allows the built-in Random LB policy to be configured via the LB policy
 // extension point. See the :ref:`load balancing architecture overview

api/envoy/extensions/load_balancing_policies/round_robin/v3/round_robin.proto

@@ -13,7 +13,7 @@ option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/loa
 option (udpa.annotations.file_status).package_version_status = ACTIVE;
 
 // [#protodoc-title: Round Robin Load Balancing Policy]
-// [#not-implemented-hide:]
+// [#extension: envoy.load_balancing_policies.round_robin]
 
 // This configuration allows the built-in ROUND_ROBIN LB policy to be configured via the LB policy
 // extension point. See the :ref:`load balancing architecture overview

changelogs/current.yaml

@@ -206,6 +206,15 @@ new_features:
 - area: http
   change: |
     allowing the dynamic forward proxy cluster to :ref:`allow_coalesced_connections <envoy_v3_api_field_extensions.clusters.dynamic_forward_proxy.v3.ClusterConfig.allow_coalesced_connections>`  for HTTP/2 and HTTP/3 connections.
+- area: upstream
+  change: |
+    added :ref:`least request extension <envoy_v3_api_msg_extensions.load_balancing_policies.least_request.v3.LeastRequest>` to suppport the :ref:`load balancer policy <envoy_v3_api_field_config.cluster.v3.Cluster.load_balancing_policy>`.
+- area: upstream
+  change: |
+    added :ref:`random extension <envoy_v3_api_msg_extensions.load_balancing_policies.random.v3.Random>` to suppport the :ref:`load balancer policy <envoy_v3_api_field_config.cluster.v3.Cluster.load_balancing_policy>`.
+- area: upstream
+  change: |
+    added :ref:`round robin extension <envoy_v3_api_msg_extensions.load_balancing_policies.round_robin.v3.RoundRobin>` to suppport the :ref:`load balancer policy <envoy_v3_api_field_config.cluster.v3.Cluster.load_balancing_policy>`.
 - area: generic_proxy
   change: |
     added :ref:`generic rds support <envoy_v3_api_field_extensions.filters.network.generic_proxy.v3.GenericProxy.generic_rds>`.

docs/root/api-v3/config/config.rst

@@ -42,3 +42,4 @@ Extensions
   upstream/upstream
   wasm/wasm
   watchdog/watchdog
+  load_balancing_policies/load_balancing_policies

docs/root/api-v3/config/load_balancing_policies/load_balancing_policies.rst

@@ -0,0 +1,10 @@
+.. _envoy_v3_api_config_load_balancer_policies:
+
+Load balancing policies
+=======================
+
+.. toctree::
+  :glob:
+  :maxdepth: 2
+
+  ../../extensions/load_balancing_policies/*/v3/*

docs/root/intro/arch_overview/upstream/load_balancing_policies.rst

@@ -0,0 +1,39 @@
+Load balancing policies
+=======================
+
+Extendable load balancing policies could be configured for each cluster by
+:ref:`load balancer policy <envoy_v3_api_field_config.cluster.v3.Cluster.load_balancing_policy>`.
+And the developer can implement a custom load balancing policy and configured it.
+
+
+See built-in load balancing policies by :ref:`APIs <envoy_v3_api_config_load_balancer_policies>`.
+
+
+:ref:`Enum based load balancing policies <envoy_v3_api_field_config.cluster.v3.Cluster.lb_policy>`
+will be suupported for backward compatibility and marked as deprecated. The new extendable load
+balancing policies should be used as a priority if the related policies are implemented.
+
+
+Use :ref:`random load balancing policy <envoy_v3_api_msg_extensions.load_balancing_policies.random.v3.Random>`
+as an example:
+
+.. code-block:: yaml
+
+    name: example_cluster
+    type: STRICT_DNS
+    connect_timeout: 0.25s
+    load_assignment:
+      cluster_name: example_cluster
+      endpoints:
+      - lb_endpoints:
+        - endpoint:
+            address:
+              socket_address:
+                address: example.com
+                port_value: 80
+    load_balancing_policy:
+      policies:
+      - typed_extension_config:
+          name: envoy.load_balancing_policies.random
+          typed_config:
+            "@type": type.googleapis.com/envoy.extensions.load_balancing_policies.random.v3.Random

docs/root/intro/arch_overview/upstream/upstream.rst

@@ -17,3 +17,4 @@ Upstream clusters
   circuit_breaking
   upstream_filters
   load_reporting_service
+  load_balancing_policies

source/common/upstream/BUILD

@@ -265,6 +265,10 @@ envoy_cc_library(
         "//source/common/protobuf:utility_lib",
         "//source/common/runtime:runtime_protos_lib",
         "@envoy_api//envoy/config/cluster/v3:pkg_cc_proto",
+        "@envoy_api//envoy/extensions/load_balancing_policies/common/v3:pkg_cc_proto",
+        "@envoy_api//envoy/extensions/load_balancing_policies/least_request/v3:pkg_cc_proto",
+        "@envoy_api//envoy/extensions/load_balancing_policies/random/v3:pkg_cc_proto",
+        "@envoy_api//envoy/extensions/load_balancing_policies/round_robin/v3:pkg_cc_proto",
     ],
 )
 

source/common/upstream/load_balancer_impl.cc

@@ -77,6 +77,36 @@ bool hostWeightsAreEqual(const HostVector& hosts) {
 
 } // namespace
 
+absl::optional<envoy::extensions::load_balancing_policies::common::v3::LocalityLbConfig>
+LoadBalancerConfigHelper::localityLbConfigFromCommonLbConfig(
+    const envoy::config::cluster::v3::Cluster::CommonLbConfig& common_config) {
+
+  if (common_config.has_locality_weighted_lb_config()) {
+    envoy::extensions::load_balancing_policies::common::v3::LocalityLbConfig locality_lb_config;
+    locality_lb_config.mutable_locality_weighted_lb_config();
+    return locality_lb_config;
+  } else if (common_config.has_zone_aware_lb_config()) {
+    envoy::extensions::load_balancing_policies::common::v3::LocalityLbConfig locality_lb_config;
+    auto& zone_aware_lb_config = *locality_lb_config.mutable_zone_aware_lb_config();
+
+    const auto& legacy_zone_aware_lb_config = common_config.zone_aware_lb_config();
+    if (legacy_zone_aware_lb_config.has_routing_enabled()) {
+      *zone_aware_lb_config.mutable_routing_enabled() =
+          legacy_zone_aware_lb_config.routing_enabled();
+    }
+    if (legacy_zone_aware_lb_config.has_min_cluster_size()) {
+      *zone_aware_lb_config.mutable_min_cluster_size() =
+          legacy_zone_aware_lb_config.min_cluster_size();
+    }
+    zone_aware_lb_config.set_fail_traffic_on_panic(
+        legacy_zone_aware_lb_config.fail_traffic_on_panic());
+
+    return locality_lb_config;
+  }
+
+  return {};
+}
+
 std::pair<uint32_t, LoadBalancerBase::HostAvailability>
 LoadBalancerBase::choosePriority(uint64_t hash, const HealthyLoad& healthy_per_priority_load,
                                  const DegradedLoad& degraded_per_priority_load) {
@@ -108,14 +138,11 @@ LoadBalancerBase::choosePriority(uint64_t hash, const HealthyLoad& healthy_per_p
   return {0, HostAvailability::Healthy};
 }
 
-LoadBalancerBase::LoadBalancerBase(
-    const PrioritySet& priority_set, ClusterLbStats& stats, Runtime::Loader& runtime,
-    Random::RandomGenerator& random,
-    const envoy::config::cluster::v3::Cluster::CommonLbConfig& common_config)
+LoadBalancerBase::LoadBalancerBase(const PrioritySet& priority_set, ClusterLbStats& stats,
+                                   Runtime::Loader& runtime, Random::RandomGenerator& random,
+                                   uint32_t healthy_panic_threshold)
     : stats_(stats), runtime_(runtime), random_(random),
-      default_healthy_panic_percent_(PROTOBUF_PERCENT_TO_ROUNDED_INTEGER_OR_DEFAULT(
-          common_config, healthy_panic_threshold, 100, 50)),
-      priority_set_(priority_set) {
+      default_healthy_panic_percent_(healthy_panic_threshold), priority_set_(priority_set) {
   for (auto& host_set : priority_set_.hostSetsPerPriority()) {
     recalculatePerPriorityState(host_set->priority(), priority_set_, per_priority_load_,
                                 per_priority_health_, per_priority_degraded_, total_healthy_hosts_);
@@ -352,16 +379,23 @@ LoadBalancerBase::chooseHostSet(LoadBalancerContext* context, uint64_t hash) con
 
 ZoneAwareLoadBalancerBase::ZoneAwareLoadBalancerBase(
     const PrioritySet& priority_set, const PrioritySet* local_priority_set, ClusterLbStats& stats,
-    Runtime::Loader& runtime, Random::RandomGenerator& random,
-    const envoy::config::cluster::v3::Cluster::CommonLbConfig& common_config)
-    : LoadBalancerBase(priority_set, stats, runtime, random, common_config),
+    Runtime::Loader& runtime, Random::RandomGenerator& random, uint32_t healthy_panic_threshold,
+    const absl::optional<LocalityLbConfig> locality_config)
+    : LoadBalancerBase(priority_set, stats, runtime, random, healthy_panic_threshold),
       local_priority_set_(local_priority_set),
-      locality_weighted_balancing_(common_config.has_locality_weighted_lb_config()),
-      routing_enabled_(PROTOBUF_PERCENT_TO_ROUNDED_INTEGER_OR_DEFAULT(
-          common_config.zone_aware_lb_config(), routing_enabled, 100, 100)),
-      min_cluster_size_(PROTOBUF_GET_WRAPPED_OR_DEFAULT(common_config.zone_aware_lb_config(),
-                                                        min_cluster_size, 6U)),
-      fail_traffic_on_panic_(common_config.zone_aware_lb_config().fail_traffic_on_panic()) {
+      locality_weighted_balancing_(locality_config.has_value() &&
+                                   locality_config->has_locality_weighted_lb_config()),
+      routing_enabled_(locality_config.has_value()
+                           ? PROTOBUF_PERCENT_TO_ROUNDED_INTEGER_OR_DEFAULT(
+                                 locality_config->zone_aware_lb_config(), routing_enabled, 100, 100)
+                           : 100),
+      min_cluster_size_(locality_config.has_value()
+                            ? PROTOBUF_GET_WRAPPED_OR_DEFAULT(
+                                  locality_config->zone_aware_lb_config(), min_cluster_size, 6U)
+                            : 6U),
+      fail_traffic_on_panic_(locality_config.has_value()
+                                 ? locality_config->zone_aware_lb_config().fail_traffic_on_panic()
+                                 : false) {
   ASSERT(!priority_set.hostSetsPerPriority().empty());
   resizePerPriorityState();
   priority_update_cb_ = priority_set_.addPriorityUpdateCb(
@@ -727,12 +761,11 @@ const HostVector& ZoneAwareLoadBalancerBase::hostSourceToHosts(HostsSource hosts
 
 EdfLoadBalancerBase::EdfLoadBalancerBase(
     const PrioritySet& priority_set, const PrioritySet* local_priority_set, ClusterLbStats& stats,
-    Runtime::Loader& runtime, Random::RandomGenerator& random,
-    const envoy::config::cluster::v3::Cluster::CommonLbConfig& common_config,
-    const absl::optional<envoy::config::cluster::v3::Cluster::SlowStartConfig> slow_start_config,
-    TimeSource& time_source)
+    Runtime::Loader& runtime, Random::RandomGenerator& random, uint32_t healthy_panic_threshold,
+    const absl::optional<LocalityLbConfig> locality_config,
+    const absl::optional<SlowStartConfig> slow_start_config, TimeSource& time_source)
     : ZoneAwareLoadBalancerBase(priority_set, local_priority_set, stats, runtime, random,
-                                common_config),
+                                healthy_panic_threshold, locality_config),
       seed_(random_.random()),
       slow_start_window_(slow_start_config.has_value()
                              ? std::chrono::milliseconds(DurationUtil::durationToMilliseconds(