From e147b5ebfb8aae4c3e2a5adf398ab408ec7c89c2 Mon Sep 17 00:00:00 2001 From: Terry Wilson Date: Fri, 29 Apr 2022 14:42:27 -0700 Subject: [PATCH] cds: Import Envoy load balancing extension protos. (#9133) --- xds/third_party/envoy/import.sh | 3 + .../ring_hash/v3/ring_hash.proto | 74 +++++++++++++++++++ .../round_robin/v3/round_robin.proto | 26 +++++++ .../wrr_locality/v3/wrr_locality.proto | 25 +++++++ 4 files changed, 128 insertions(+) create mode 100644 xds/third_party/envoy/src/main/proto/envoy/extensions/load_balancing_policies/ring_hash/v3/ring_hash.proto create mode 100644 xds/third_party/envoy/src/main/proto/envoy/extensions/load_balancing_policies/round_robin/v3/round_robin.proto create mode 100644 xds/third_party/envoy/src/main/proto/envoy/extensions/load_balancing_policies/wrr_locality/v3/wrr_locality.proto diff --git a/xds/third_party/envoy/import.sh b/xds/third_party/envoy/import.sh index 992b2d15b7..f8f0cf3420 100755 --- a/xds/third_party/envoy/import.sh +++ b/xds/third_party/envoy/import.sh @@ -129,6 +129,9 @@ envoy/extensions/filters/http/fault/v3/fault.proto envoy/extensions/filters/http/rbac/v3/rbac.proto envoy/extensions/filters/http/router/v3/router.proto envoy/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto +envoy/extensions/load_balancing_policies/ring_hash/v3/ring_hash.proto +envoy/extensions/load_balancing_policies/round_robin/v3/round_robin.proto +envoy/extensions/load_balancing_policies/wrr_locality/v3/wrr_locality.proto envoy/extensions/transport_sockets/tls/v3/cert.proto envoy/extensions/transport_sockets/tls/v3/common.proto envoy/extensions/transport_sockets/tls/v3/secret.proto diff --git a/xds/third_party/envoy/src/main/proto/envoy/extensions/load_balancing_policies/ring_hash/v3/ring_hash.proto b/xds/third_party/envoy/src/main/proto/envoy/extensions/load_balancing_policies/ring_hash/v3/ring_hash.proto new file mode 100644 index 0000000000..9408734bec --- /dev/null +++ b/xds/third_party/envoy/src/main/proto/envoy/extensions/load_balancing_policies/ring_hash/v3/ring_hash.proto @@ -0,0 +1,74 @@ +syntax = "proto3"; + +package envoy.extensions.load_balancing_policies.ring_hash.v3; + +import "google/protobuf/wrappers.proto"; + +import "udpa/annotations/status.proto"; +import "validate/validate.proto"; + +option java_package = "io.envoyproxy.envoy.extensions.load_balancing_policies.ring_hash.v3"; +option java_outer_classname = "RingHashProto"; +option java_multiple_files = true; +option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/load_balancing_policies/ring_hash/v3;ring_hashv3"; +option (udpa.annotations.file_status).package_version_status = ACTIVE; + +// [#protodoc-title: Ring Hash Load Balancing Policy] + +// 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.clusters.lb_policy] +// [#next-free-field: 6] +message RingHash { + // The hash function used to hash hosts onto the ketama ring. + enum HashFunction { + // Currently defaults to XX_HASH. + DEFAULT_HASH = 0; + + // Use `xxHash `_. + XX_HASH = 1; + + // Use `MurmurHash2 `_, this is compatible with + // std:hash in GNU libstdc++ 3.4.20 or above. This is typically the case when compiled + // on Linux and not macOS. + MURMUR_HASH_2 = 2; + } + + // The hash function used to hash hosts onto the ketama ring. The value defaults to + // :ref:`XX_HASH`. + HashFunction hash_function = 1 [(validate.rules).enum = {defined_only: true}]; + + // Minimum hash ring size. The larger the ring is (that is, the more hashes there are for each + // provided host) the better the request distribution will reflect the desired weights. Defaults + // to 1024 entries, and limited to 8M entries. See also + // :ref:`maximum_ring_size`. + google.protobuf.UInt64Value minimum_ring_size = 2 [(validate.rules).uint64 = {lte: 8388608}]; + + // Maximum hash ring size. Defaults to 8M entries, and limited to 8M entries, but can be lowered + // to further constrain resource use. See also + // :ref:`minimum_ring_size`. + google.protobuf.UInt64Value maximum_ring_size = 3 [(validate.rules).uint64 = {lte: 8388608}]; + + // 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; + + // 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. + // + // 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 = 5 [(validate.rules).uint32 = {gte: 100}]; +} diff --git a/xds/third_party/envoy/src/main/proto/envoy/extensions/load_balancing_policies/round_robin/v3/round_robin.proto b/xds/third_party/envoy/src/main/proto/envoy/extensions/load_balancing_policies/round_robin/v3/round_robin.proto new file mode 100644 index 0000000000..4875b632f9 --- /dev/null +++ b/xds/third_party/envoy/src/main/proto/envoy/extensions/load_balancing_policies/round_robin/v3/round_robin.proto @@ -0,0 +1,26 @@ +syntax = "proto3"; + +package envoy.extensions.load_balancing_policies.round_robin.v3; + +import "envoy/config/cluster/v3/cluster.proto"; + +import "udpa/annotations/status.proto"; +import "validate/validate.proto"; + +option java_package = "io.envoyproxy.envoy.extensions.load_balancing_policies.round_robin.v3"; +option java_outer_classname = "RoundRobinProto"; +option java_multiple_files = true; +option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/load_balancing_policies/round_robin/v3;round_robinv3"; +option (udpa.annotations.file_status).package_version_status = ACTIVE; + +// [#protodoc-title: Round Robin Load Balancing Policy] + +// 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.clusters.lb_policy] +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; +} diff --git a/xds/third_party/envoy/src/main/proto/envoy/extensions/load_balancing_policies/wrr_locality/v3/wrr_locality.proto b/xds/third_party/envoy/src/main/proto/envoy/extensions/load_balancing_policies/wrr_locality/v3/wrr_locality.proto new file mode 100644 index 0000000000..cad403dd35 --- /dev/null +++ b/xds/third_party/envoy/src/main/proto/envoy/extensions/load_balancing_policies/wrr_locality/v3/wrr_locality.proto @@ -0,0 +1,25 @@ +syntax = "proto3"; + +package envoy.extensions.load_balancing_policies.wrr_locality.v3; + +import "envoy/config/cluster/v3/cluster.proto"; + +import "udpa/annotations/status.proto"; +import "validate/validate.proto"; + +option java_package = "io.envoyproxy.envoy.extensions.load_balancing_policies.wrr_locality.v3"; +option java_outer_classname = "WrrLocalityProto"; +option java_multiple_files = true; +option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/load_balancing_policies/wrr_locality/v3;wrr_localityv3"; +option (udpa.annotations.file_status).package_version_status = ACTIVE; + +// [#protodoc-title: Weighted Round Robin Locality-Picking Load Balancing Policy] + +// Configuration for the wrr_locality LB policy. See the :ref:`load balancing architecture overview +// ` for more information. +// [#extension: envoy.clusters.lb_policy] +message WrrLocality { + // The child LB policy to create for endpoint-picking within the chosen locality. + config.cluster.v3.LoadBalancingPolicy endpoint_picking_policy = 1 + [(validate.rules).message = {required: true}]; +}