From 194681eadd5de1f7a2d2044919fe0ca34da1b8d9 Mon Sep 17 00:00:00 2001 From: "data-plane-api(Azure Pipelines)" Date: Wed, 7 Dec 2022 14:49:32 +0000 Subject: [PATCH] lb api: moving load balancing policy specific configuration to extension configuration (#23967) Signed-off-by: wbpcode Mirrored from https://github.com/envoyproxy/envoy @ 50ac04b41af595f1df9a925146bd5314201ca425 --- BUILD | 7 ++ .../load_balancing_policies/common/v3/BUILD | 13 ++ .../common/v3/common.proto | 115 ++++++++++++++++++ .../least_request/v3/BUILD | 2 +- .../least_request/v3/least_request.proto | 8 +- .../load_balancing_policies/maglev/v3/BUILD | 5 +- .../maglev/v3/maglev.proto | 6 +- .../load_balancing_policies/random/v3/BUILD | 5 +- .../random/v3/random.proto | 5 +- .../ring_hash/v3/BUILD | 6 +- .../ring_hash/v3/ring_hash.proto | 26 +++- .../round_robin/v3/BUILD | 2 +- .../round_robin/v3/round_robin.proto | 8 +- .../wrr_locality/v3/wrr_locality.proto | 2 +- versioning/BUILD | 1 + 15 files changed, 193 insertions(+), 18 deletions(-) create mode 100644 envoy/extensions/load_balancing_policies/common/v3/BUILD create mode 100644 envoy/extensions/load_balancing_policies/common/v3/common.proto diff --git a/BUILD b/BUILD index 53f57c57..42744b01 100644 --- a/BUILD +++ b/BUILD @@ -240,6 +240,13 @@ proto_library( "//envoy/extensions/internal_redirect/previous_routes/v3:pkg", "//envoy/extensions/internal_redirect/safe_cross_scheme/v3:pkg", "//envoy/extensions/key_value/file_based/v3:pkg", + "//envoy/extensions/load_balancing_policies/common/v3:pkg", + "//envoy/extensions/load_balancing_policies/least_request/v3:pkg", + "//envoy/extensions/load_balancing_policies/maglev/v3:pkg", + "//envoy/extensions/load_balancing_policies/random/v3:pkg", + "//envoy/extensions/load_balancing_policies/ring_hash/v3:pkg", + "//envoy/extensions/load_balancing_policies/round_robin/v3:pkg", + "//envoy/extensions/load_balancing_policies/wrr_locality/v3:pkg", "//envoy/extensions/matching/common_inputs/environment_variable/v3:pkg", "//envoy/extensions/matching/common_inputs/network/v3:pkg", "//envoy/extensions/matching/common_inputs/ssl/v3:pkg", diff --git a/envoy/extensions/load_balancing_policies/common/v3/BUILD b/envoy/extensions/load_balancing_policies/common/v3/BUILD new file mode 100644 index 00000000..ad2fc9a9 --- /dev/null +++ b/envoy/extensions/load_balancing_policies/common/v3/BUILD @@ -0,0 +1,13 @@ +# DO NOT EDIT. This file is generated by tools/proto_format/proto_sync.py. + +load("@envoy_api//bazel:api_build_system.bzl", "api_proto_package") + +licenses(["notice"]) # Apache 2 + +api_proto_package( + deps = [ + "//envoy/config/core/v3:pkg", + "//envoy/type/v3:pkg", + "@com_github_cncf_udpa//udpa/annotations:pkg", + ], +) diff --git a/envoy/extensions/load_balancing_policies/common/v3/common.proto b/envoy/extensions/load_balancing_policies/common/v3/common.proto new file mode 100644 index 00000000..a19765f7 --- /dev/null +++ b/envoy/extensions/load_balancing_policies/common/v3/common.proto @@ -0,0 +1,115 @@ +syntax = "proto3"; + +package envoy.extensions.load_balancing_policies.common.v3; + +import "envoy/config/core/v3/base.proto"; +import "envoy/type/v3/percent.proto"; + +import "google/protobuf/duration.proto"; +import "google/protobuf/wrappers.proto"; + +import "udpa/annotations/status.proto"; +import "validate/validate.proto"; + +option java_package = "io.envoyproxy.envoy.extensions.load_balancing_policies.common.v3"; +option java_outer_classname = "CommonProto"; +option java_multiple_files = true; +option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/load_balancing_policies/common/v3;commonv3"; +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 + // `. + message ZoneAwareLbConfig { + // Configures percentage of requests that will be considered for zone aware routing + // if zone aware routing is configured. If not specified, the default is 100%. + // * :ref:`runtime values `. + // * :ref:`Zone aware routing support `. + type.v3.Percent routing_enabled = 1; + + // Configures minimum upstream cluster size required for zone aware routing + // If upstream cluster size is less than specified, zone aware routing is not performed + // even if zone aware routing is configured. If not specified, the default is 6. + // * :ref:`runtime values `. + // * :ref:`Zone aware routing support `. + google.protobuf.UInt64Value min_cluster_size = 2; + + // If set to true, Envoy will not consider any hosts when the cluster is in :ref:`panic + // mode`. Instead, the cluster will fail all + // requests as if all hosts are unhealthy. This can help avoid potentially overwhelming a + // failing service. + bool fail_traffic_on_panic = 3; + } + + // Configuration for :ref:`locality weighted load balancing + // ` + message LocalityWeightedLbConfig { + } + + oneof locality_config_specifier { + option (validate.required) = true; + + // Configuration for local zone aware load balancing. + ZoneAwareLbConfig zone_aware_lb_config = 1; + + // Enable locality weighted load balancing. + LocalityWeightedLbConfig locality_weighted_lb_config = 2; + } +} + +// Configuration for :ref:`slow start mode `. +message SlowStartConfig { + // Represents the size of slow start window. + // If set, the newly created host remains in slow start mode starting from its creation time + // for the duration of slow start window. + google.protobuf.Duration slow_start_window = 1; + + // This parameter controls the speed of traffic increase over the slow start window. Defaults to 1.0, + // so that endpoint would get linearly increasing amount of traffic. + // When increasing the value for this parameter, the speed of traffic ramp-up increases non-linearly. + // The value of aggression parameter should be greater than 0.0. + // By tuning the parameter, is possible to achieve polynomial or exponential shape of ramp-up curve. + // + // During slow start window, effective weight of an endpoint would be scaled with time factor and aggression: + // ``new_weight = weight * max(min_weight_percent, time_factor ^ (1 / aggression))``, + // where ``time_factor=(time_since_start_seconds / slow_start_time_seconds)``. + // + // As time progresses, more and more traffic would be sent to endpoint, which is in slow start window. + // Once host exits slow start, time_factor and aggression no longer affect its weight. + config.core.v3.RuntimeDouble aggression = 2; + + // Configures the minimum percentage of origin weight that avoids too small new weight, + // which may cause endpoints in slow start mode receive no traffic in slow start window. + // If not specified, the default is 10%. + type.v3.Percent min_weight_percent = 3; +} + +// Common Configuration for all consistent hashing load balancers (MaglevLb, RingHashLb, etc.) +message ConsistentHashingLbConfig { + // If set to ``true``, the cluster will use hostname instead of the resolved + // 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. + bool use_hostname_for_hashing = 1; + + // Configures percentage of average cluster load to bound per upstream host. For example, with a value of 150 + // no upstream host will get a load more than 1.5 times the average load of all the hosts in the cluster. + // If not specified, the load is not bounded for any upstream host. Typical value for this parameter is between 120 and 200. + // Minimum is 100. + // + // Applies to both Ring Hash and Maglev load balancers. + // + // This is implemented based on the method described in the paper https://arxiv.org/abs/1608.01350. For the specified + // ``hash_balance_factor``, requests to any upstream host are capped at ``hash_balance_factor/100`` times the average number of requests + // across the cluster. When a request arrives for an upstream host that is currently serving at its max capacity, linear probing + // is used to identify an eligible host. Further, the linear probe is implemented using a random jump in hosts ring/table to identify + // the eligible host (this technique is as described in the paper https://arxiv.org/abs/1908.08762 - the random jump avoids the + // cascading overflow effect when choosing the next host in the ring/table). + // + // If weights are specified on the hosts, they are respected. + // + // This is an O(N) algorithm, unlike other load balancers. Using a lower ``hash_balance_factor`` results in more hosts + // being probed, so use a higher value if you require better performance. + google.protobuf.UInt32Value hash_balance_factor = 2 [(validate.rules).uint32 = {gte: 100}]; +} diff --git a/envoy/extensions/load_balancing_policies/least_request/v3/BUILD b/envoy/extensions/load_balancing_policies/least_request/v3/BUILD index 2a87d27d..366a3c32 100644 --- a/envoy/extensions/load_balancing_policies/least_request/v3/BUILD +++ b/envoy/extensions/load_balancing_policies/least_request/v3/BUILD @@ -6,8 +6,8 @@ licenses(["notice"]) # Apache 2 api_proto_package( deps = [ - "//envoy/config/cluster/v3:pkg", "//envoy/config/core/v3:pkg", + "//envoy/extensions/load_balancing_policies/common/v3:pkg", "@com_github_cncf_udpa//udpa/annotations:pkg", ], ) diff --git a/envoy/extensions/load_balancing_policies/least_request/v3/least_request.proto b/envoy/extensions/load_balancing_policies/least_request/v3/least_request.proto index fd34260d..d6eb834a 100644 --- a/envoy/extensions/load_balancing_policies/least_request/v3/least_request.proto +++ b/envoy/extensions/load_balancing_policies/least_request/v3/least_request.proto @@ -2,8 +2,8 @@ syntax = "proto3"; package envoy.extensions.load_balancing_policies.least_request.v3; -import "envoy/config/cluster/v3/cluster.proto"; import "envoy/config/core/v3/base.proto"; +import "envoy/extensions/load_balancing_policies/common/v3/common.proto"; import "google/protobuf/wrappers.proto"; @@ -22,7 +22,6 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // 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 // ` for more information. -// [#extension: envoy.load_balancing_policies] message LeastRequest { // The number of random healthy hosts from which the host with the fewest active requests will // be chosen. Defaults to 2 so that we perform two-choice selection if the field is not set. @@ -55,5 +54,8 @@ message LeastRequest { // Configuration for slow start mode. // If this configuration is not set, slow start will not be not enabled. - config.cluster.v3.Cluster.SlowStartConfig slow_start_config = 3; + common.v3.SlowStartConfig slow_start_config = 3; + + // Configuration for local zone aware load balancing or locality weighted load balancing. + common.v3.LocalityLbConfig locality_lb_config = 4; } diff --git a/envoy/extensions/load_balancing_policies/maglev/v3/BUILD b/envoy/extensions/load_balancing_policies/maglev/v3/BUILD index ee92fb65..6a0be4c9 100644 --- a/envoy/extensions/load_balancing_policies/maglev/v3/BUILD +++ b/envoy/extensions/load_balancing_policies/maglev/v3/BUILD @@ -5,5 +5,8 @@ load("@envoy_api//bazel:api_build_system.bzl", "api_proto_package") licenses(["notice"]) # Apache 2 api_proto_package( - deps = ["@com_github_cncf_udpa//udpa/annotations:pkg"], + deps = [ + "//envoy/extensions/load_balancing_policies/common/v3:pkg", + "@com_github_cncf_udpa//udpa/annotations:pkg", + ], ) diff --git a/envoy/extensions/load_balancing_policies/maglev/v3/maglev.proto b/envoy/extensions/load_balancing_policies/maglev/v3/maglev.proto index 4ed884fd..d34920a7 100644 --- a/envoy/extensions/load_balancing_policies/maglev/v3/maglev.proto +++ b/envoy/extensions/load_balancing_policies/maglev/v3/maglev.proto @@ -2,6 +2,8 @@ syntax = "proto3"; package envoy.extensions.load_balancing_policies.maglev.v3; +import "envoy/extensions/load_balancing_policies/common/v3/common.proto"; + import "google/protobuf/wrappers.proto"; import "udpa/annotations/status.proto"; @@ -19,11 +21,13 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // This configuration allows the built-in Maglev LB policy to be configured via the LB policy // extension point. See the :ref:`load balancing architecture overview // ` and :ref:`Maglev` for more information. -// [#extension: envoy.load_balancing_policies] message Maglev { // The table size for Maglev hashing. Maglev aims for "minimal disruption" rather than an absolute guarantee. // Minimal disruption means that when the set of upstream hosts change, a connection will likely be sent to the same // upstream as it was before. Increasing the table size reduces the amount of disruption. // The table size must be prime number limited to 5000011. If it is not specified, the default is 65537. google.protobuf.UInt64Value table_size = 1 [(validate.rules).uint64 = {lte: 5000011}]; + + // Common configuration for hashing-based load balancing policies. + common.v3.ConsistentHashingLbConfig consistent_hashing_lb_config = 2; } diff --git a/envoy/extensions/load_balancing_policies/random/v3/BUILD b/envoy/extensions/load_balancing_policies/random/v3/BUILD index ee92fb65..6a0be4c9 100644 --- a/envoy/extensions/load_balancing_policies/random/v3/BUILD +++ b/envoy/extensions/load_balancing_policies/random/v3/BUILD @@ -5,5 +5,8 @@ load("@envoy_api//bazel:api_build_system.bzl", "api_proto_package") licenses(["notice"]) # Apache 2 api_proto_package( - deps = ["@com_github_cncf_udpa//udpa/annotations:pkg"], + deps = [ + "//envoy/extensions/load_balancing_policies/common/v3:pkg", + "@com_github_cncf_udpa//udpa/annotations:pkg", + ], ) diff --git a/envoy/extensions/load_balancing_policies/random/v3/random.proto b/envoy/extensions/load_balancing_policies/random/v3/random.proto index 1d01dfba..37efa7c1 100644 --- a/envoy/extensions/load_balancing_policies/random/v3/random.proto +++ b/envoy/extensions/load_balancing_policies/random/v3/random.proto @@ -2,6 +2,8 @@ syntax = "proto3"; package envoy.extensions.load_balancing_policies.random.v3; +import "envoy/extensions/load_balancing_policies/common/v3/common.proto"; + import "udpa/annotations/status.proto"; option java_package = "io.envoyproxy.envoy.extensions.load_balancing_policies.random.v3"; @@ -16,6 +18,7 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // 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 // ` for more information. -// [#extension: envoy.load_balancing_policies] message Random { + // Configuration for local zone aware load balancing or locality weighted load balancing. + common.v3.LocalityLbConfig locality_lb_config = 1; } diff --git a/envoy/extensions/load_balancing_policies/ring_hash/v3/BUILD b/envoy/extensions/load_balancing_policies/ring_hash/v3/BUILD index ee92fb65..9ec681aa 100644 --- a/envoy/extensions/load_balancing_policies/ring_hash/v3/BUILD +++ b/envoy/extensions/load_balancing_policies/ring_hash/v3/BUILD @@ -5,5 +5,9 @@ load("@envoy_api//bazel:api_build_system.bzl", "api_proto_package") licenses(["notice"]) # Apache 2 api_proto_package( - deps = ["@com_github_cncf_udpa//udpa/annotations:pkg"], + deps = [ + "//envoy/annotations:pkg", + "//envoy/extensions/load_balancing_policies/common/v3:pkg", + "@com_github_cncf_udpa//udpa/annotations:pkg", + ], ) diff --git a/envoy/extensions/load_balancing_policies/ring_hash/v3/ring_hash.proto b/envoy/extensions/load_balancing_policies/ring_hash/v3/ring_hash.proto index 0001b6ee..fa1da5fa 100644 --- a/envoy/extensions/load_balancing_policies/ring_hash/v3/ring_hash.proto +++ b/envoy/extensions/load_balancing_policies/ring_hash/v3/ring_hash.proto @@ -2,8 +2,11 @@ syntax = "proto3"; package envoy.extensions.load_balancing_policies.ring_hash.v3; +import "envoy/extensions/load_balancing_policies/common/v3/common.proto"; + import "google/protobuf/wrappers.proto"; +import "envoy/annotations/deprecation.proto"; import "udpa/annotations/status.proto"; import "validate/validate.proto"; @@ -19,8 +22,7 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // This configuration allows the built-in RING_HASH LB policy to be configured via the LB policy // extension point. See the :ref:`load balancing architecture overview // ` for more information. -// [#extension: envoy.load_balancing_policies] -// [#next-free-field: 6] +// [#next-free-field: 7] message RingHash { // The hash function used to hash hosts onto the ketama ring. enum HashFunction { @@ -53,7 +55,12 @@ message RingHash { // If set to `true`, the cluster will use hostname instead of the resolved // 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. - bool use_hostname_for_hashing = 4; + // + // ..note:: + // This is deprecated and please use :ref:`consistent_hashing_lb_config + // ` instead. + bool use_hostname_for_hashing = 4 + [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"]; // Configures percentage of average cluster load to bound per upstream host. For example, with a value of 150 // no upstream host will get a load more than 1.5 times the average load of all the hosts in the cluster. @@ -71,5 +78,16 @@ message RingHash { // // This is an O(N) algorithm, unlike other load balancers. Using a lower `hash_balance_factor` results in more hosts // being probed, so use a higher value if you require better performance. - google.protobuf.UInt32Value hash_balance_factor = 5 [(validate.rules).uint32 = {gte: 100}]; + // + // ..note:: + // This is deprecated and please use :ref:`consistent_hashing_lb_config + // ` instead. + google.protobuf.UInt32Value hash_balance_factor = 5 [ + deprecated = true, + (validate.rules).uint32 = {gte: 100}, + (envoy.annotations.deprecated_at_minor_version) = "3.0" + ]; + + // Common configuration for hashing-based load balancing policies. + common.v3.ConsistentHashingLbConfig consistent_hashing_lb_config = 6; } diff --git a/envoy/extensions/load_balancing_policies/round_robin/v3/BUILD b/envoy/extensions/load_balancing_policies/round_robin/v3/BUILD index b49ae907..6a0be4c9 100644 --- a/envoy/extensions/load_balancing_policies/round_robin/v3/BUILD +++ b/envoy/extensions/load_balancing_policies/round_robin/v3/BUILD @@ -6,7 +6,7 @@ licenses(["notice"]) # Apache 2 api_proto_package( deps = [ - "//envoy/config/cluster/v3:pkg", + "//envoy/extensions/load_balancing_policies/common/v3:pkg", "@com_github_cncf_udpa//udpa/annotations:pkg", ], ) diff --git a/envoy/extensions/load_balancing_policies/round_robin/v3/round_robin.proto b/envoy/extensions/load_balancing_policies/round_robin/v3/round_robin.proto index 1ef8fc81..01b8a62e 100644 --- a/envoy/extensions/load_balancing_policies/round_robin/v3/round_robin.proto +++ b/envoy/extensions/load_balancing_policies/round_robin/v3/round_robin.proto @@ -2,7 +2,7 @@ syntax = "proto3"; package envoy.extensions.load_balancing_policies.round_robin.v3; -import "envoy/config/cluster/v3/cluster.proto"; +import "envoy/extensions/load_balancing_policies/common/v3/common.proto"; import "udpa/annotations/status.proto"; @@ -18,9 +18,11 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // 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 // ` for more information. -// [#extension: envoy.load_balancing_policies] message RoundRobin { // Configuration for slow start mode. // If this configuration is not set, slow start will not be not enabled. - config.cluster.v3.Cluster.SlowStartConfig slow_start_config = 1; + common.v3.SlowStartConfig slow_start_config = 1; + + // Configuration for local zone aware load balancing or locality weighted load balancing. + common.v3.LocalityLbConfig locality_lb_config = 2; } diff --git a/envoy/extensions/load_balancing_policies/wrr_locality/v3/wrr_locality.proto b/envoy/extensions/load_balancing_policies/wrr_locality/v3/wrr_locality.proto index 855cbf8f..ab8367a4 100644 --- a/envoy/extensions/load_balancing_policies/wrr_locality/v3/wrr_locality.proto +++ b/envoy/extensions/load_balancing_policies/wrr_locality/v3/wrr_locality.proto @@ -14,10 +14,10 @@ option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/loa option (udpa.annotations.file_status).package_version_status = ACTIVE; // [#protodoc-title: Weighted Round Robin Locality-Picking Load Balancing Policy] +// [#not-implemented-hide:] // Configuration for the wrr_locality LB policy. See the :ref:`load balancing architecture overview // ` for more information. -// [#extension: envoy.load_balancing_policies] message WrrLocality { // The child LB policy to create for endpoint-picking within the chosen locality. config.cluster.v3.LoadBalancingPolicy endpoint_picking_policy = 1 diff --git a/versioning/BUILD b/versioning/BUILD index 51bbfa80..a0a178b4 100644 --- a/versioning/BUILD +++ b/versioning/BUILD @@ -178,6 +178,7 @@ proto_library( "//envoy/extensions/internal_redirect/previous_routes/v3:pkg", "//envoy/extensions/internal_redirect/safe_cross_scheme/v3:pkg", "//envoy/extensions/key_value/file_based/v3:pkg", + "//envoy/extensions/load_balancing_policies/common/v3:pkg", "//envoy/extensions/load_balancing_policies/least_request/v3:pkg", "//envoy/extensions/load_balancing_policies/maglev/v3:pkg", "//envoy/extensions/load_balancing_policies/random/v3:pkg",