1syntax = "proto3";
2
3package envoy.extensions.load_balancing_policies.common.v3;
4
5import "envoy/config/core/v3/base.proto";
6import "envoy/type/v3/percent.proto";
7
8import "google/protobuf/duration.proto";
9import "google/protobuf/wrappers.proto";
10
11import "udpa/annotations/status.proto";
12import "validate/validate.proto";
13
14option java_package = "io.envoyproxy.envoy.extensions.load_balancing_policies.common.v3";
15option java_outer_classname = "CommonProto";
16option java_multiple_files = true;
17option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/load_balancing_policies/common/v3;commonv3";
18option (udpa.annotations.file_status).package_version_status = ACTIVE;
19
20// [#protodoc-title: Common configuration for two or more load balancing policy extensions]
21
22message LocalityLbConfig {
23  // Configuration for :ref:`zone aware routing
24  // <arch_overview_load_balancing_zone_aware_routing>`.
25  message ZoneAwareLbConfig {
26    // Configures percentage of requests that will be considered for zone aware routing
27    // if zone aware routing is configured. If not specified, the default is 100%.
28    // * :ref:`runtime values <config_cluster_manager_cluster_runtime_zone_routing>`.
29    // * :ref:`Zone aware routing support <arch_overview_load_balancing_zone_aware_routing>`.
30    type.v3.Percent routing_enabled = 1;
31
32    // Configures minimum upstream cluster size required for zone aware routing
33    // If upstream cluster size is less than specified, zone aware routing is not performed
34    // even if zone aware routing is configured. If not specified, the default is 6.
35    // * :ref:`runtime values <config_cluster_manager_cluster_runtime_zone_routing>`.
36    // * :ref:`Zone aware routing support <arch_overview_load_balancing_zone_aware_routing>`.
37    google.protobuf.UInt64Value min_cluster_size = 2;
38
39    // If set to true, Envoy will not consider any hosts when the cluster is in :ref:`panic
40    // mode<arch_overview_load_balancing_panic_threshold>`. Instead, the cluster will fail all
41    // requests as if all hosts are unhealthy. This can help avoid potentially overwhelming a
42    // failing service.
43    bool fail_traffic_on_panic = 3;
44  }
45
46  // Configuration for :ref:`locality weighted load balancing
47  // <arch_overview_load_balancing_locality_weighted_lb>`
48  message LocalityWeightedLbConfig {
49  }
50
51  oneof locality_config_specifier {
52    option (validate.required) = true;
53
54    // Configuration for local zone aware load balancing.
55    ZoneAwareLbConfig zone_aware_lb_config = 1;
56
57    // Enable locality weighted load balancing.
58    LocalityWeightedLbConfig locality_weighted_lb_config = 2;
59  }
60}
61
62// Configuration for :ref:`slow start mode <arch_overview_load_balancing_slow_start>`.
63message SlowStartConfig {
64  // Represents the size of slow start window.
65  // If set, the newly created host remains in slow start mode starting from its creation time
66  // for the duration of slow start window.
67  google.protobuf.Duration slow_start_window = 1;
68
69  // This parameter controls the speed of traffic increase over the slow start window. Defaults to 1.0,
70  // so that endpoint would get linearly increasing amount of traffic.
71  // When increasing the value for this parameter, the speed of traffic ramp-up increases non-linearly.
72  // The value of aggression parameter should be greater than 0.0.
73  // By tuning the parameter, is possible to achieve polynomial or exponential shape of ramp-up curve.
74  //
75  // During slow start window, effective weight of an endpoint would be scaled with time factor and aggression:
76  // ``new_weight = weight * max(min_weight_percent, time_factor ^ (1 / aggression))``,
77  // where ``time_factor=(time_since_start_seconds / slow_start_time_seconds)``.
78  //
79  // As time progresses, more and more traffic would be sent to endpoint, which is in slow start window.
80  // Once host exits slow start, time_factor and aggression no longer affect its weight.
81  config.core.v3.RuntimeDouble aggression = 2;
82
83  // Configures the minimum percentage of origin weight that avoids too small new weight,
84  // which may cause endpoints in slow start mode receive no traffic in slow start window.
85  // If not specified, the default is 10%.
86  type.v3.Percent min_weight_percent = 3;
87}
88
89// Common Configuration for all consistent hashing load balancers (MaglevLb, RingHashLb, etc.)
90message ConsistentHashingLbConfig {
91  // If set to ``true``, the cluster will use hostname instead of the resolved
92  // address as the key to consistently hash to an upstream host. Only valid for StrictDNS clusters with hostnames which resolve to a single IP address.
93  bool use_hostname_for_hashing = 1;
94
95  // Configures percentage of average cluster load to bound per upstream host. For example, with a value of 150
96  // no upstream host will get a load more than 1.5 times the average load of all the hosts in the cluster.
97  // If not specified, the load is not bounded for any upstream host. Typical value for this parameter is between 120 and 200.
98  // Minimum is 100.
99  //
100  // Applies to both Ring Hash and Maglev load balancers.
101  //
102  // This is implemented based on the method described in the paper https://arxiv.org/abs/1608.01350. For the specified
103  // ``hash_balance_factor``, requests to any upstream host are capped at ``hash_balance_factor/100`` times the average number of requests
104  // across the cluster. When a request arrives for an upstream host that is currently serving at its max capacity, linear probing
105  // is used to identify an eligible host. Further, the linear probe is implemented using a random jump in hosts ring/table to identify
106  // the eligible host (this technique is as described in the paper https://arxiv.org/abs/1908.08762 - the random jump avoids the
107  // cascading overflow effect when choosing the next host in the ring/table).
108  //
109  // If weights are specified on the hosts, they are respected.
110  //
111  // This is an O(N) algorithm, unlike other load balancers. Using a lower ``hash_balance_factor`` results in more hosts
112  // being probed, so use a higher value if you require better performance.
113  google.protobuf.UInt32Value hash_balance_factor = 2 [(validate.rules).uint32 = {gte: 100}];
114}
115