Support slow Start mode in Envoy

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

@@ -439,7 +439,7 @@ message Cluster {
   }
 
   // Common configuration for all load balancer implementations.
-  // [#next-free-field: 8]
+  // [#next-free-field: 9]
   message CommonLbConfig {
     option (udpa.annotations.versioning).previous_message_type =
         "envoy.api.v2.Cluster.CommonLbConfig";
@@ -507,6 +507,26 @@ message Cluster {
       google.protobuf.UInt32Value hash_balance_factor = 2 [(validate.rules).uint32 = {gte: 100}];
     }
 
+    // Configuration for :ref:`slow start mode <arch_overview_load_balancing_slow_start>`.
+    message SlowStartConfig {
+      // Size of slow start window in seconds, should be set to value greater than zero.
+      // If set, the newly created host remains in slow start mode starting from its creation time
+      // for the duration of slow start window.
+      uint32 slow_start_window = 1 [(validate.rules).uint32 = {gt: 0}];
+
+      // This parameter linearly affects load balancing weight of an endpoint. Defaults to 1.0.
+      // The smaller the time bias is, the less traffic would be sent to endpoint that is within slow start window.
+      // The value of time bias should be greater than or equal to 0.0 and less than or equal to 1.0.
+      // If slow start window and time bias are configured, effective weight of an endpoint would be scaled with time bias and time factor during the duration of slow start window:
+      // `weight = load_balancing_weight * time_bias * time_factor`,
+      // where  `time_factor = (1 / slow_start_window_in_seconds) * host_create_duration_in_seconds`.
+      //
+      // When `time bias == 0.0` the Round Robin and Least Request Load Balancers will not scale endpoint weight with time bias
+      // and will behave as if slow start is not enabled.
+      // Once host exits slow start, its weight is no longer being scaled with time bias parameter.
+      core.v3.RuntimeDouble time_bias = 3;
+    }
+
     // Configures the :ref:`healthy panic threshold <arch_overview_load_balancing_panic_threshold>`.
     // If not specified, the default is 50%.
     // To disable panic mode, set to 0%.
@@ -548,6 +568,10 @@ message Cluster {
 
     // Common Configuration for all consistent hashing load balancers (MaglevLb, RingHashLb, etc.)
     ConsistentHashingLbConfig consistent_hashing_lb_config = 7;
+
+    // Configuration for slow start mode.
+    // If this configuration is not set, slow start will not be not enabled.
+    SlowStartConfig slow_start_config = 8;
   }
 
   message RefreshRate {

api/envoy/config/cluster/v4alpha/cluster.proto

@@ -443,7 +443,7 @@ message Cluster {
   }
 
   // Common configuration for all load balancer implementations.
-  // [#next-free-field: 8]
+  // [#next-free-field: 9]
   message CommonLbConfig {
     option (udpa.annotations.versioning).previous_message_type =
         "envoy.config.cluster.v3.Cluster.CommonLbConfig";
@@ -511,6 +511,29 @@ message Cluster {
       google.protobuf.UInt32Value hash_balance_factor = 2 [(validate.rules).uint32 = {gte: 100}];
     }
 
+    // Configuration for :ref:`slow start mode <arch_overview_load_balancing_slow_start>`.
+    message SlowStartConfig {
+      option (udpa.annotations.versioning).previous_message_type =
+          "envoy.config.cluster.v3.Cluster.CommonLbConfig.SlowStartConfig";
+
+      // Size of slow start window in seconds, should be set to value greater than zero.
+      // If set, the newly created host remains in slow start mode starting from its creation time
+      // for the duration of slow start window.
+      uint32 slow_start_window = 1 [(validate.rules).uint32 = {gt: 0}];
+
+      // This parameter linearly affects load balancing weight of an endpoint. Defaults to 1.0.
+      // The smaller the time bias is, the less traffic would be sent to endpoint that is within slow start window.
+      // The value of time bias should be greater than or equal to 0.0 and less than or equal to 1.0.
+      // If slow start window and time bias are configured, effective weight of an endpoint would be scaled with time bias and time factor during the duration of slow start window:
+      // `weight = load_balancing_weight * time_bias * time_factor`,
+      // where  `time_factor = (1 / slow_start_window_in_seconds) * host_create_duration_in_seconds`.
+      //
+      // When `time bias == 0.0` the Round Robin and Least Request Load Balancers will not scale endpoint weight with time bias
+      // and will behave as if slow start is not enabled.
+      // Once host exits slow start, its weight is no longer being scaled with time bias parameter.
+      core.v4alpha.RuntimeDouble time_bias = 3;
+    }
+
     // Configures the :ref:`healthy panic threshold <arch_overview_load_balancing_panic_threshold>`.
     // If not specified, the default is 50%.
     // To disable panic mode, set to 0%.
@@ -552,6 +575,10 @@ message Cluster {
 
     // Common Configuration for all consistent hashing load balancers (MaglevLb, RingHashLb, etc.)
     ConsistentHashingLbConfig consistent_hashing_lb_config = 7;
+
+    // Configuration for slow start mode.
+    // If this configuration is not set, slow start will not be not enabled.
+    SlowStartConfig slow_start_config = 8;
   }
 
   message RefreshRate {

bazel/repositories.bzl

@@ -547,6 +547,10 @@ def _com_google_absl():
         name = "abseil_node_hash_set",
         actual = "@com_google_absl//absl/container:node_hash_set",
     )
+    native.bind(
+        name = "abseil_btree",
+        actual = "@com_google_absl//absl/container:btree",
+    )
     native.bind(
         name = "abseil_str_format",
         actual = "@com_google_absl//absl/strings:str_format",

docs/root/configuration/listeners/udp_filters/dns_filter.rst

@@ -104,7 +104,7 @@ Envoy will return no addresses and set the response code appropriately. Converse
 matching records for the query type, each configured address is returned. This is also true for
 AAAA records. Only A, AAAA, and SRV records are supported. If the filter parses queries for other
 record types, the filter immediately responds indicating that the type is not supported. The
-filter can also redirect a query for a DNS name to the enpoints of a cluster. "www.domain4.com"
+filter can also redirect a query for a DNS name to the endpoints of a cluster. "www.domain4.com"
 in the configuration demonstrates this. Along with an address list, a cluster name is a valid
 endpoint for a DNS name.
 

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

@@ -15,3 +15,4 @@ Load Balancing
   original_dst
   zone_aware
   subsets
+  slow_start

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

@@ -0,0 +1,57 @@
+.. _arch_overview_load_balancing_slow_start:
+
+Slow start mode
+===============
+
+Slow start mode is a configuration setting in Envoy to progressively increase amount of traffic for newly added upstream endpoints.
+With no slow start enabled Envoy would send a proportional amount of traffic to new upstream ednpoints.
+This could be undesirable for services that require warm up time to serve full production load and could result in request timeouts, loss of data and deteriorated user experience.
+
+Slow start mode is a mechanism that affects load balancing weight of upstream endpoints and can be configured per upstream cluster. 
+Currently, slow start is supported in Round Robin and Least Request load balancer types.
+
+Users can specify a :ref:`slow start window parameter<envoy_v3_api_field_config.cluster.v3.Cluster.CommonLbConfig.SlowStartConfig.slow_start_window>` (in seconds), so that if endpoint “cluster membership duration" (amount of time since it has joined the cluster) is within the configured window, it enters slow start mode. 
+During slow start window, load balancing weight of a particular endpoint will be scaled with :ref:`time bias parameter<envoy_v3_api_field_config.cluster.v3.Cluster.CommonLbConfig.SlowStartConfig.time_bias>`, e.g.:
+`weight = load_balancing_weight * time_bias * time_factor`.
+Time factor is value that increases as time progresses, and is calculated like:
+`time_factor = (1 / slow_start_window_seconds) * endpoint_create_duration_seconds`
+
+The longer slow start window is the less traffic would be sent to endpoint as time advances within slow start window.
+
+Whenever a slow start window duration elapses, upstream endpoint exits slow start mode and gets regular amount of traffic acccording to load balanacing algorithm.
+Its load balancing weight will no longer be scaled with runtime bias. Endpoint could also exit slow start mode in case it leaves the cluster.
+
+To reiterate, endpoint enters slow start mode when:
+  * If no active healthcheck is configured per cluster, immediately if its cluster membership duration is within slow start window.
+  * In case an active healthcheck is configured per cluster, when its cluster membership duration is within slow start window and endpoint has passed an active healthcheck. 
+    If endpoint does not pass an active healcheck during entire slow start window (since it has been added to upstream cluster), then it never enters slow start mode.
+
+Endpoint exits slow start mode when:
+  * It leaves the cluster.
+  * Its cluster membership duration is greater than slow start window.
+  * It does not pass an active healcheck configured per cluster.
+    Endpoint could further re-enter slow start, if it passes an active healtcheck and its creation time is within slow start window.
+
+Below is example of how requests would be distributed across endpoints with Round Robin Loadbalancer, slow start window of 10 seconds, no active healcheck and 0.5 time bias.
+Endpoint E1 has statically configured initial weight of X and endpoint E2 weight of Y, the actual numerical values are of no significance for this example.
+
++-------------+--------------------+------------+------------+-----------+----------+-------------+
+| Timestamp   | Event              | E1 in slow | E2 in slow | E1 LB     | E2 LB    | LB decision |
+|             |                    | start      | start      | weight    | weight   |             |
++=============+====================+============+============+===========+==========+=============+
+| 1           |  E1 create         |    YES     |     --     |   0.5X    |    --    |     --      |
++-------------+--------------------+------------+------------+-----------+----------+-------------+
+| 11          |  E2 create         |     NO     |    YES     |    X      |   0.5Y   |     --      |
++-------------+--------------------+------------+------------+-----------+----------+-------------+
+| 12          | LB select endpoint |     NO     |    YES     |    X      |   0.5Y   |     E1      | 
++-------------+--------------------+------------+------------+-----------+----------+-------------+
+| 13          | LB select endpoint |     NO     |    YES     |    X      |   0.5Y   |     E1      | 
++-------------+--------------------+------------+------------+-----------+----------+-------------+
+| 14          | LB select endpoint |     NO     |    YES     |    X      |   0.5Y   |     E1      | 
++-------------+--------------------+------------+------------+-----------+----------+-------------+
+| 15          |LB select endpoint  |     NO     |    YES     |    X      |   0.5Y   |     E2      | 
++-------------+--------------------+------------+------------+-----------+----------+-------------+
+| 22          | LB select endpoint |     NO     |     NO     |    X      |    Y     |     E1      | 
++-------------+--------------------+------------+------------+-----------+----------+-------------+
+| 23          | LB select endpoint |     NO     |     NO     |    X      |    Y     |     E2      | 
++-------------+--------------------+------------+------------+-----------+----------+-------------+

source/common/upstream/BUILD

@@ -177,6 +177,7 @@ envoy_cc_library(
     name = "load_balancer_lib",
     srcs = ["load_balancer_impl.cc"],
     hdrs = ["load_balancer_impl.h"],
+    external_deps = ["abseil_btree"],
     deps = [
         ":edf_scheduler_lib",
         "//include/envoy/common:random_generator_interface",

source/common/upstream/cluster_manager_impl.cc

@@ -1315,14 +1315,16 @@ ClusterManagerImpl::ThreadLocalClusterManagerImpl::ClusterEntry::ClusterEntry(
         cluster->lbType(), priority_set_, parent_.local_priority_set_, cluster->stats(),
         cluster->statsScope(), parent.parent_.runtime_, parent.parent_.random_,
         cluster->lbSubsetInfo(), cluster->lbRingHashConfig(), cluster->lbMaglevConfig(),
-        cluster->lbLeastRequestConfig(), cluster->lbConfig());
+        cluster->lbLeastRequestConfig(), cluster->lbConfig(),
+        parent_.thread_local_dispatcher_.timeSource());
   } else {
     switch (cluster->lbType()) {
     case LoadBalancerType::LeastRequest: {
       ASSERT(lb_factory_ == nullptr);
       lb_ = std::make_unique<LeastRequestLoadBalancer>(
           priority_set_, parent_.local_priority_set_, cluster->stats(), parent.parent_.runtime_,
-          parent.parent_.random_, cluster->lbConfig(), cluster->lbLeastRequestConfig());
+          parent.parent_.random_, cluster->lbConfig(), cluster->lbLeastRequestConfig(),
+          parent.thread_local_dispatcher_.timeSource());
       break;
     }
     case LoadBalancerType::Random: {
@@ -1336,7 +1338,8 @@ ClusterManagerImpl::ThreadLocalClusterManagerImpl::ClusterEntry::ClusterEntry(
       ASSERT(lb_factory_ == nullptr);
       lb_ = std::make_unique<RoundRobinLoadBalancer>(priority_set_, parent_.local_priority_set_,
                                                      cluster->stats(), parent.parent_.runtime_,
-                                                     parent.parent_.random_, cluster->lbConfig());
+                                                     parent.parent_.random_, cluster->lbConfig(),
+                                                     parent.thread_local_dispatcher_.timeSource());
       break;
     }
     case LoadBalancerType::ClusterProvided: