forked from envoyproxy/envoy
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
api: new subset lb extension api (envoyproxy#27256)
* api: new subset lb extension api Signed-off-by: wbpcode <[email protected]> * fix proto format Signed-off-by: wbpcode <[email protected]> * address comment Signed-off-by: wbpcode <[email protected]> * add previous message type Signed-off-by: wbpcode <[email protected]> --------- Signed-off-by: wbpcode <[email protected]>
- Loading branch information
code
authored
May 15, 2023
1 parent
2ede973
commit 39b25c0
Showing
4 changed files
with
234 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
12 changes: 12 additions & 0 deletions
12
api/envoy/extensions/load_balancing_policies/subset/v3/BUILD
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,12 @@ | ||
| # 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/cluster/v3:pkg", | ||
| "@com_github_cncf_udpa//udpa/annotations:pkg", | ||
| ], | ||
| ) |
220 changes: 220 additions & 0 deletions
220
api/envoy/extensions/load_balancing_policies/subset/v3/subset.proto
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,220 @@ | ||
| syntax = "proto3"; | ||
|
|
||
| package envoy.extensions.load_balancing_policies.subset.v3; | ||
|
|
||
| import "envoy/config/cluster/v3/cluster.proto"; | ||
|
|
||
| import "google/protobuf/struct.proto"; | ||
|
|
||
| import "udpa/annotations/status.proto"; | ||
| import "udpa/annotations/versioning.proto"; | ||
| import "validate/validate.proto"; | ||
|
|
||
| option java_package = "io.envoyproxy.envoy.extensions.load_balancing_policies.subset.v3"; | ||
| option java_outer_classname = "SubsetProto"; | ||
| option java_multiple_files = true; | ||
| option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/load_balancing_policies/subset/v3;subsetv3"; | ||
| option (udpa.annotations.file_status).package_version_status = ACTIVE; | ||
|
|
||
| // [#protodoc-title: Subset Load Balancing Policy] | ||
| // [#extension: envoy.load_balancing_policies.subset] | ||
| // [#not-implemented-hide:] | ||
|
|
||
| // Optionally divide the endpoints in this cluster into subsets defined by | ||
| // endpoint metadata and selected by route and weighted cluster metadata. | ||
| // [#next-free-field: 10] | ||
| message Subset { | ||
| option (udpa.annotations.versioning).previous_message_type = | ||
| "envoy.config.cluster.v3.LbSubsetConfig"; | ||
|
|
||
| // If NO_FALLBACK is selected, a result | ||
| // equivalent to no healthy hosts is reported. If ANY_ENDPOINT is selected, | ||
| // any cluster endpoint may be returned (subject to policy, health checks, | ||
| // etc). If DEFAULT_SUBSET is selected, load balancing is performed over the | ||
| // endpoints matching the values from the default_subset field. | ||
| enum LbSubsetFallbackPolicy { | ||
| NO_FALLBACK = 0; | ||
| ANY_ENDPOINT = 1; | ||
| DEFAULT_SUBSET = 2; | ||
| } | ||
|
|
||
| enum LbSubsetMetadataFallbackPolicy { | ||
| // No fallback. Route metadata will be used as-is. | ||
| METADATA_NO_FALLBACK = 0; | ||
|
|
||
| // A special metadata key ``fallback_list`` will be used to provide variants of metadata to try. | ||
| // Value of ``fallback_list`` key has to be a list. Every list element has to be a struct - it will | ||
| // be merged with route metadata, overriding keys that appear in both places. | ||
| // ``fallback_list`` entries will be used in order until a host is found. | ||
| // | ||
| // ``fallback_list`` key itself is removed from metadata before subset load balancing is performed. | ||
| // | ||
| // Example: | ||
| // | ||
| // for metadata: | ||
| // | ||
| // .. code-block:: yaml | ||
| // | ||
| // version: 1.0 | ||
| // fallback_list: | ||
| // - version: 2.0 | ||
| // hardware: c64 | ||
| // - hardware: c32 | ||
| // - version: 3.0 | ||
| // | ||
| // at first, metadata: | ||
| // | ||
| // .. code-block:: json | ||
| // | ||
| // {"version": "2.0", "hardware": "c64"} | ||
| // | ||
| // will be used for load balancing. If no host is found, metadata: | ||
| // | ||
| // .. code-block:: json | ||
| // | ||
| // {"version": "1.0", "hardware": "c32"} | ||
| // | ||
| // is next to try. If it still results in no host, finally metadata: | ||
| // | ||
| // .. code-block:: json | ||
| // | ||
| // {"version": "3.0"} | ||
| // | ||
| // is used. | ||
| FALLBACK_LIST = 1; | ||
| } | ||
|
|
||
| // Specifications for subsets. | ||
| message LbSubsetSelector { | ||
| // Allows to override top level fallback policy per selector. | ||
| enum LbSubsetSelectorFallbackPolicy { | ||
| // If NOT_DEFINED top level config fallback policy is used instead. | ||
| NOT_DEFINED = 0; | ||
|
|
||
| // If NO_FALLBACK is selected, a result equivalent to no healthy hosts is reported. | ||
| NO_FALLBACK = 1; | ||
|
|
||
| // If ANY_ENDPOINT is selected, any cluster endpoint may be returned | ||
| // (subject to policy, health checks, etc). | ||
| ANY_ENDPOINT = 2; | ||
|
|
||
| // If DEFAULT_SUBSET is selected, load balancing is performed over the | ||
| // endpoints matching the values from the default_subset field. | ||
| DEFAULT_SUBSET = 3; | ||
|
|
||
| // If KEYS_SUBSET is selected, subset selector matching is performed again with metadata | ||
| // keys reduced to | ||
| // :ref:`fallback_keys_subset<envoy_v3_api_field_config.cluster.v3.Cluster.LbSubsetConfig.LbSubsetSelector.fallback_keys_subset>`. | ||
| // It allows for a fallback to a different, less specific selector if some of the keys of | ||
| // the selector are considered optional. | ||
| KEYS_SUBSET = 4; | ||
| } | ||
|
|
||
| // List of keys to match with the weighted cluster metadata. | ||
| repeated string keys = 1; | ||
|
|
||
| // Selects a mode of operation in which each subset has only one host. This mode uses the same rules for | ||
| // choosing a host, but updating hosts is faster, especially for large numbers of hosts. | ||
| // | ||
| // If a match is found to a host, that host will be used regardless of priority levels. | ||
| // | ||
| // When this mode is enabled, configurations that contain more than one host with the same metadata value for the single key in ``keys`` | ||
| // will use only one of the hosts with the given key; no requests will be routed to the others. The cluster gauge | ||
| // :ref:`lb_subsets_single_host_per_subset_duplicate<config_cluster_manager_cluster_stats_subset_lb>` indicates how many duplicates are | ||
| // present in the current configuration. | ||
| bool single_host_per_subset = 4; | ||
|
|
||
| // The behavior used when no endpoint subset matches the selected route's | ||
| // metadata. | ||
| LbSubsetSelectorFallbackPolicy fallback_policy = 2 | ||
| [(validate.rules).enum = {defined_only: true}]; | ||
|
|
||
| // Subset of | ||
| // :ref:`keys<envoy_v3_api_field_config.cluster.v3.Cluster.LbSubsetConfig.LbSubsetSelector.keys>` used by | ||
| // :ref:`KEYS_SUBSET<envoy_v3_api_enum_value_config.cluster.v3.Cluster.LbSubsetConfig.LbSubsetSelector.LbSubsetSelectorFallbackPolicy.KEYS_SUBSET>` | ||
| // fallback policy. | ||
| // It has to be a non empty list if KEYS_SUBSET fallback policy is selected. | ||
| // For any other fallback policy the parameter is not used and should not be set. | ||
| // Only values also present in | ||
| // :ref:`keys<envoy_v3_api_field_config.cluster.v3.Cluster.LbSubsetConfig.LbSubsetSelector.keys>` are allowed, but | ||
| // ``fallback_keys_subset`` cannot be equal to ``keys``. | ||
| repeated string fallback_keys_subset = 3; | ||
| } | ||
|
|
||
| // The behavior used when no endpoint subset matches the selected route's | ||
| // metadata. The value defaults to | ||
| // :ref:`NO_FALLBACK<envoy_v3_api_enum_value_config.cluster.v3.Cluster.LbSubsetConfig.LbSubsetFallbackPolicy.NO_FALLBACK>`. | ||
| LbSubsetFallbackPolicy fallback_policy = 1 [(validate.rules).enum = {defined_only: true}]; | ||
|
|
||
| // Specifies the default subset of endpoints used during fallback if | ||
| // fallback_policy is | ||
| // :ref:`DEFAULT_SUBSET<envoy_v3_api_enum_value_config.cluster.v3.Cluster.LbSubsetConfig.LbSubsetFallbackPolicy.DEFAULT_SUBSET>`. | ||
| // Each field in default_subset is | ||
| // compared to the matching LbEndpoint.Metadata under the ``envoy.lb`` | ||
| // namespace. It is valid for no hosts to match, in which case the behavior | ||
| // is the same as a fallback_policy of | ||
| // :ref:`NO_FALLBACK<envoy_v3_api_enum_value_config.cluster.v3.Cluster.LbSubsetConfig.LbSubsetFallbackPolicy.NO_FALLBACK>`. | ||
| google.protobuf.Struct default_subset = 2; | ||
|
|
||
| // For each entry, LbEndpoint.Metadata's | ||
| // ``envoy.lb`` namespace is traversed and a subset is created for each unique | ||
| // combination of key and value. For example: | ||
| // | ||
| // .. code-block:: json | ||
| // | ||
| // { "subset_selectors": [ | ||
| // { "keys": [ "version" ] }, | ||
| // { "keys": [ "stage", "hardware_type" ] } | ||
| // ]} | ||
| // | ||
| // A subset is matched when the metadata from the selected route and | ||
| // weighted cluster contains the same keys and values as the subset's | ||
| // metadata. The same host may appear in multiple subsets. | ||
| repeated LbSubsetSelector subset_selectors = 3; | ||
|
|
||
| // If true, routing to subsets will take into account the localities and locality weights of the | ||
| // endpoints when making the routing decision. | ||
| // | ||
| // There are some potential pitfalls associated with enabling this feature, as the resulting | ||
| // traffic split after applying both a subset match and locality weights might be undesirable. | ||
| // | ||
| // Consider for example a situation in which you have 50/50 split across two localities X/Y | ||
| // which have 100 hosts each without subsetting. If the subset LB results in X having only 1 | ||
| // host selected but Y having 100, then a lot more load is being dumped on the single host in X | ||
| // than originally anticipated in the load balancing assignment delivered via EDS. | ||
| bool locality_weight_aware = 4; | ||
|
|
||
| // When used with locality_weight_aware, scales the weight of each locality by the ratio | ||
| // of hosts in the subset vs hosts in the original subset. This aims to even out the load | ||
| // going to an individual locality if said locality is disproportionately affected by the | ||
| // subset predicate. | ||
| bool scale_locality_weight = 5; | ||
|
|
||
| // If true, when a fallback policy is configured and its corresponding subset fails to find | ||
| // a host this will cause any host to be selected instead. | ||
| // | ||
| // This is useful when using the default subset as the fallback policy, given the default | ||
| // subset might become empty. With this option enabled, if that happens the LB will attempt | ||
| // to select a host from the entire cluster. | ||
| bool panic_mode_any = 6; | ||
|
|
||
| // If true, metadata specified for a metadata key will be matched against the corresponding | ||
| // endpoint metadata if the endpoint metadata matches the value exactly OR it is a list value | ||
| // and any of the elements in the list matches the criteria. | ||
| bool list_as_any = 7; | ||
|
|
||
| // Fallback mechanism that allows to try different route metadata until a host is found. | ||
| // If load balancing process, including all its mechanisms (like | ||
| // :ref:`fallback_policy<envoy_v3_api_field_extensions.load_balancing_policies.subset.v3.subset.fallback_policy>`) | ||
| // fails to select a host, this policy decides if and how the process is repeated using another metadata. | ||
| // | ||
| // The value defaults to | ||
| // :ref:`METADATA_NO_FALLBACK | ||
| // <envoy_v3_api_field_extensions.load_balancing_policies.subset.v3.subset.LbSubsetMetadataFallbackPolicy.METADATA_NO_FALLBACK>`. | ||
| LbSubsetMetadataFallbackPolicy metadata_fallback_policy = 8 | ||
| [(validate.rules).enum = {defined_only: true}]; | ||
|
|
||
| // The child LB policy to create for endpoint-picking within the chosen subset. | ||
| config.cluster.v3.LoadBalancingPolicy subset_lb_policy = 9 | ||
| [(validate.rules).message = {required: true}]; | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters