...

Text file src/github.com/datawire/ambassador/v2/api/envoy/config/cluster/v3/cluster.proto

Documentation: github.com/datawire/ambassador/v2/api/envoy/config/cluster/v3

     1syntax = "proto3";
     2
     3package envoy.config.cluster.v3;
     4
     5import "envoy/config/cluster/v3/circuit_breaker.proto";
     6import "envoy/config/cluster/v3/filter.proto";
     7import "envoy/config/cluster/v3/outlier_detection.proto";
     8import "envoy/config/core/v3/address.proto";
     9import "envoy/config/core/v3/base.proto";
    10import "envoy/config/core/v3/config_source.proto";
    11import "envoy/config/core/v3/extension.proto";
    12import "envoy/config/core/v3/health_check.proto";
    13import "envoy/config/core/v3/protocol.proto";
    14import "envoy/config/endpoint/v3/endpoint.proto";
    15import "envoy/type/v3/percent.proto";
    16
    17import "google/protobuf/any.proto";
    18import "google/protobuf/duration.proto";
    19import "google/protobuf/struct.proto";
    20import "google/protobuf/wrappers.proto";
    21
    22import "xds/core/v3/collection_entry.proto";
    23
    24import "envoy/annotations/deprecation.proto";
    25import "udpa/annotations/migrate.proto";
    26import "udpa/annotations/security.proto";
    27import "udpa/annotations/status.proto";
    28import "udpa/annotations/versioning.proto";
    29import "validate/validate.proto";
    30
    31option java_package = "io.envoyproxy.envoy.config.cluster.v3";
    32option java_outer_classname = "ClusterProto";
    33option java_multiple_files = true;
    34option (udpa.annotations.file_status).package_version_status = ACTIVE;
    35
    36// [#protodoc-title: Cluster configuration]
    37
    38// Cluster list collections. Entries are *Cluster* resources or references.
    39// [#not-implemented-hide:]
    40message ClusterCollection {
    41  xds.core.v3.CollectionEntry entries = 1;
    42}
    43
    44// Configuration for a single upstream cluster.
    45// [#next-free-field: 53]
    46message Cluster {
    47  option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.Cluster";
    48
    49  // Refer to :ref:`service discovery type <arch_overview_service_discovery_types>`
    50  // for an explanation on each type.
    51  enum DiscoveryType {
    52    // Refer to the :ref:`static discovery type<arch_overview_service_discovery_types_static>`
    53    // for an explanation.
    54    STATIC = 0;
    55
    56    // Refer to the :ref:`strict DNS discovery
    57    // type<arch_overview_service_discovery_types_strict_dns>`
    58    // for an explanation.
    59    STRICT_DNS = 1;
    60
    61    // Refer to the :ref:`logical DNS discovery
    62    // type<arch_overview_service_discovery_types_logical_dns>`
    63    // for an explanation.
    64    LOGICAL_DNS = 2;
    65
    66    // Refer to the :ref:`service discovery type<arch_overview_service_discovery_types_eds>`
    67    // for an explanation.
    68    EDS = 3;
    69
    70    // Refer to the :ref:`original destination discovery
    71    // type<arch_overview_service_discovery_types_original_destination>`
    72    // for an explanation.
    73    ORIGINAL_DST = 4;
    74  }
    75
    76  // Refer to :ref:`load balancer type <arch_overview_load_balancing_types>` architecture
    77  // overview section for information on each type.
    78  enum LbPolicy {
    79    reserved 4;
    80
    81    reserved "ORIGINAL_DST_LB";
    82
    83    // Refer to the :ref:`round robin load balancing
    84    // policy<arch_overview_load_balancing_types_round_robin>`
    85    // for an explanation.
    86    ROUND_ROBIN = 0;
    87
    88    // Refer to the :ref:`least request load balancing
    89    // policy<arch_overview_load_balancing_types_least_request>`
    90    // for an explanation.
    91    LEAST_REQUEST = 1;
    92
    93    // Refer to the :ref:`ring hash load balancing
    94    // policy<arch_overview_load_balancing_types_ring_hash>`
    95    // for an explanation.
    96    RING_HASH = 2;
    97
    98    // Refer to the :ref:`random load balancing
    99    // policy<arch_overview_load_balancing_types_random>`
   100    // for an explanation.
   101    RANDOM = 3;
   102
   103    // Refer to the :ref:`Maglev load balancing policy<arch_overview_load_balancing_types_maglev>`
   104    // for an explanation.
   105    MAGLEV = 5;
   106
   107    // This load balancer type must be specified if the configured cluster provides a cluster
   108    // specific load balancer. Consult the configured cluster's documentation for whether to set
   109    // this option or not.
   110    CLUSTER_PROVIDED = 6;
   111
   112    // [#not-implemented-hide:] Use the new :ref:`load_balancing_policy
   113    // <envoy_api_field_config.cluster.v3.Cluster.load_balancing_policy>` field to determine the LB policy.
   114    // [#next-major-version: In the v3 API, we should consider deprecating the lb_policy field
   115    // and instead using the new load_balancing_policy field as the one and only mechanism for
   116    // configuring this.]
   117    LOAD_BALANCING_POLICY_CONFIG = 7;
   118  }
   119
   120  // When V4_ONLY is selected, the DNS resolver will only perform a lookup for
   121  // addresses in the IPv4 family. If V6_ONLY is selected, the DNS resolver will
   122  // only perform a lookup for addresses in the IPv6 family. If AUTO is
   123  // specified, the DNS resolver will first perform a lookup for addresses in
   124  // the IPv6 family and fallback to a lookup for addresses in the IPv4 family.
   125  // For cluster types other than
   126  // :ref:`STRICT_DNS<envoy_api_enum_value_config.cluster.v3.Cluster.DiscoveryType.STRICT_DNS>` and
   127  // :ref:`LOGICAL_DNS<envoy_api_enum_value_config.cluster.v3.Cluster.DiscoveryType.LOGICAL_DNS>`,
   128  // this setting is
   129  // ignored.
   130  enum DnsLookupFamily {
   131    AUTO = 0;
   132    V4_ONLY = 1;
   133    V6_ONLY = 2;
   134  }
   135
   136  enum ClusterProtocolSelection {
   137    // Cluster can only operate on one of the possible upstream protocols (HTTP1.1, HTTP2).
   138    // If :ref:`http2_protocol_options <envoy_api_field_config.cluster.v3.Cluster.http2_protocol_options>` are
   139    // present, HTTP2 will be used, otherwise HTTP1.1 will be used.
   140    USE_CONFIGURED_PROTOCOL = 0;
   141
   142    // Use HTTP1.1 or HTTP2, depending on which one is used on the downstream connection.
   143    USE_DOWNSTREAM_PROTOCOL = 1;
   144  }
   145
   146  // TransportSocketMatch specifies what transport socket config will be used
   147  // when the match conditions are satisfied.
   148  message TransportSocketMatch {
   149    option (udpa.annotations.versioning).previous_message_type =
   150        "envoy.api.v2.Cluster.TransportSocketMatch";
   151
   152    // The name of the match, used in stats generation.
   153    string name = 1 [(validate.rules).string = {min_len: 1}];
   154
   155    // Optional endpoint metadata match criteria.
   156    // The connection to the endpoint with metadata matching what is set in this field
   157    // will use the transport socket configuration specified here.
   158    // The endpoint's metadata entry in *envoy.transport_socket_match* is used to match
   159    // against the values specified in this field.
   160    google.protobuf.Struct match = 2;
   161
   162    // The configuration of the transport socket.
   163    core.v3.TransportSocket transport_socket = 3;
   164  }
   165
   166  // Extended cluster type.
   167  message CustomClusterType {
   168    option (udpa.annotations.versioning).previous_message_type =
   169        "envoy.api.v2.Cluster.CustomClusterType";
   170
   171    // The type of the cluster to instantiate. The name must match a supported cluster type.
   172    string name = 1 [(validate.rules).string = {min_len: 1}];
   173
   174    // Cluster specific configuration which depends on the cluster being instantiated.
   175    // See the supported cluster for further documentation.
   176    google.protobuf.Any typed_config = 2;
   177  }
   178
   179  // Only valid when discovery type is EDS.
   180  message EdsClusterConfig {
   181    option (udpa.annotations.versioning).previous_message_type =
   182        "envoy.api.v2.Cluster.EdsClusterConfig";
   183
   184    // Configuration for the source of EDS updates for this Cluster.
   185    core.v3.ConfigSource eds_config = 1;
   186
   187    // Optional alternative to cluster name to present to EDS. This does not
   188    // have the same restrictions as cluster name, i.e. it may be arbitrary
   189    // length. This may be a xdstp:// URL.
   190    string service_name = 2;
   191  }
   192
   193  // Optionally divide the endpoints in this cluster into subsets defined by
   194  // endpoint metadata and selected by route and weighted cluster metadata.
   195  // [#next-free-field: 8]
   196  message LbSubsetConfig {
   197    option (udpa.annotations.versioning).previous_message_type =
   198        "envoy.api.v2.Cluster.LbSubsetConfig";
   199
   200    // If NO_FALLBACK is selected, a result
   201    // equivalent to no healthy hosts is reported. If ANY_ENDPOINT is selected,
   202    // any cluster endpoint may be returned (subject to policy, health checks,
   203    // etc). If DEFAULT_SUBSET is selected, load balancing is performed over the
   204    // endpoints matching the values from the default_subset field.
   205    enum LbSubsetFallbackPolicy {
   206      NO_FALLBACK = 0;
   207      ANY_ENDPOINT = 1;
   208      DEFAULT_SUBSET = 2;
   209    }
   210
   211    // Specifications for subsets.
   212    message LbSubsetSelector {
   213      option (udpa.annotations.versioning).previous_message_type =
   214          "envoy.api.v2.Cluster.LbSubsetConfig.LbSubsetSelector";
   215
   216      // Allows to override top level fallback policy per selector.
   217      enum LbSubsetSelectorFallbackPolicy {
   218        // If NOT_DEFINED top level config fallback policy is used instead.
   219        NOT_DEFINED = 0;
   220
   221        // If NO_FALLBACK is selected, a result equivalent to no healthy hosts is reported.
   222        NO_FALLBACK = 1;
   223
   224        // If ANY_ENDPOINT is selected, any cluster endpoint may be returned
   225        // (subject to policy, health checks, etc).
   226        ANY_ENDPOINT = 2;
   227
   228        // If DEFAULT_SUBSET is selected, load balancing is performed over the
   229        // endpoints matching the values from the default_subset field.
   230        DEFAULT_SUBSET = 3;
   231
   232        // If KEYS_SUBSET is selected, subset selector matching is performed again with metadata
   233        // keys reduced to
   234        // :ref:`fallback_keys_subset<envoy_api_field_config.cluster.v3.Cluster.LbSubsetConfig.LbSubsetSelector.fallback_keys_subset>`.
   235        // It allows for a fallback to a different, less specific selector if some of the keys of
   236        // the selector are considered optional.
   237        KEYS_SUBSET = 4;
   238      }
   239
   240      // List of keys to match with the weighted cluster metadata.
   241      repeated string keys = 1;
   242
   243      // Selects a mode of operation in which each subset has only one host. This mode uses the same rules for
   244      // choosing a host, but updating hosts is faster, especially for large numbers of hosts.
   245      //
   246      // If a match is found to a host, that host will be used regardless of priority levels, unless the host is unhealthy.
   247      //
   248      // Currently, this mode is only supported if `subset_selectors` has only one entry, and `keys` contains
   249      // only one entry.
   250      //
   251      // When this mode is enabled, configurations that contain more than one host with the same metadata value for the single key in `keys`
   252      // will use only one of the hosts with the given key; no requests will be routed to the others. The cluster gauge
   253      // :ref:`lb_subsets_single_host_per_subset_duplicate<config_cluster_manager_cluster_stats_subset_lb>` indicates how many duplicates are
   254      // present in the current configuration.
   255      bool single_host_per_subset = 4;
   256
   257      // The behavior used when no endpoint subset matches the selected route's
   258      // metadata.
   259      LbSubsetSelectorFallbackPolicy fallback_policy = 2
   260          [(validate.rules).enum = {defined_only: true}];
   261
   262      // Subset of
   263      // :ref:`keys<envoy_api_field_config.cluster.v3.Cluster.LbSubsetConfig.LbSubsetSelector.keys>` used by
   264      // :ref:`KEYS_SUBSET<envoy_api_enum_value_config.cluster.v3.Cluster.LbSubsetConfig.LbSubsetSelector.LbSubsetSelectorFallbackPolicy.KEYS_SUBSET>`
   265      // fallback policy.
   266      // It has to be a non empty list if KEYS_SUBSET fallback policy is selected.
   267      // For any other fallback policy the parameter is not used and should not be set.
   268      // Only values also present in
   269      // :ref:`keys<envoy_api_field_config.cluster.v3.Cluster.LbSubsetConfig.LbSubsetSelector.keys>` are allowed, but
   270      // `fallback_keys_subset` cannot be equal to `keys`.
   271      repeated string fallback_keys_subset = 3;
   272    }
   273
   274    // The behavior used when no endpoint subset matches the selected route's
   275    // metadata. The value defaults to
   276    // :ref:`NO_FALLBACK<envoy_api_enum_value_config.cluster.v3.Cluster.LbSubsetConfig.LbSubsetFallbackPolicy.NO_FALLBACK>`.
   277    LbSubsetFallbackPolicy fallback_policy = 1 [(validate.rules).enum = {defined_only: true}];
   278
   279    // Specifies the default subset of endpoints used during fallback if
   280    // fallback_policy is
   281    // :ref:`DEFAULT_SUBSET<envoy_api_enum_value_config.cluster.v3.Cluster.LbSubsetConfig.LbSubsetFallbackPolicy.DEFAULT_SUBSET>`.
   282    // Each field in default_subset is
   283    // compared to the matching LbEndpoint.Metadata under the *envoy.lb*
   284    // namespace. It is valid for no hosts to match, in which case the behavior
   285    // is the same as a fallback_policy of
   286    // :ref:`NO_FALLBACK<envoy_api_enum_value_config.cluster.v3.Cluster.LbSubsetConfig.LbSubsetFallbackPolicy.NO_FALLBACK>`.
   287    google.protobuf.Struct default_subset = 2;
   288
   289    // For each entry, LbEndpoint.Metadata's
   290    // *envoy.lb* namespace is traversed and a subset is created for each unique
   291    // combination of key and value. For example:
   292    //
   293    // .. code-block:: json
   294    //
   295    //   { "subset_selectors": [
   296    //       { "keys": [ "version" ] },
   297    //       { "keys": [ "stage", "hardware_type" ] }
   298    //   ]}
   299    //
   300    // A subset is matched when the metadata from the selected route and
   301    // weighted cluster contains the same keys and values as the subset's
   302    // metadata. The same host may appear in multiple subsets.
   303    repeated LbSubsetSelector subset_selectors = 3;
   304
   305    // If true, routing to subsets will take into account the localities and locality weights of the
   306    // endpoints when making the routing decision.
   307    //
   308    // There are some potential pitfalls associated with enabling this feature, as the resulting
   309    // traffic split after applying both a subset match and locality weights might be undesirable.
   310    //
   311    // Consider for example a situation in which you have 50/50 split across two localities X/Y
   312    // which have 100 hosts each without subsetting. If the subset LB results in X having only 1
   313    // host selected but Y having 100, then a lot more load is being dumped on the single host in X
   314    // than originally anticipated in the load balancing assignment delivered via EDS.
   315    bool locality_weight_aware = 4;
   316
   317    // When used with locality_weight_aware, scales the weight of each locality by the ratio
   318    // of hosts in the subset vs hosts in the original subset. This aims to even out the load
   319    // going to an individual locality if said locality is disproportionately affected by the
   320    // subset predicate.
   321    bool scale_locality_weight = 5;
   322
   323    // If true, when a fallback policy is configured and its corresponding subset fails to find
   324    // a host this will cause any host to be selected instead.
   325    //
   326    // This is useful when using the default subset as the fallback policy, given the default
   327    // subset might become empty. With this option enabled, if that happens the LB will attempt
   328    // to select a host from the entire cluster.
   329    bool panic_mode_any = 6;
   330
   331    // If true, metadata specified for a metadata key will be matched against the corresponding
   332    // endpoint metadata if the endpoint metadata matches the value exactly OR it is a list value
   333    // and any of the elements in the list matches the criteria.
   334    bool list_as_any = 7;
   335  }
   336
   337  // Specific configuration for the LeastRequest load balancing policy.
   338  message LeastRequestLbConfig {
   339    option (udpa.annotations.versioning).previous_message_type =
   340        "envoy.api.v2.Cluster.LeastRequestLbConfig";
   341
   342    // The number of random healthy hosts from which the host with the fewest active requests will
   343    // be chosen. Defaults to 2 so that we perform two-choice selection if the field is not set.
   344    google.protobuf.UInt32Value choice_count = 1 [(validate.rules).uint32 = {gte: 2}];
   345
   346    // The following formula is used to calculate the dynamic weights when hosts have different load
   347    // balancing weights:
   348    //
   349    // `weight = load_balancing_weight / (active_requests + 1)^active_request_bias`
   350    //
   351    // The larger the active request bias is, the more aggressively active requests will lower the
   352    // effective weight when all host weights are not equal.
   353    //
   354    // `active_request_bias` must be greater than or equal to 0.0.
   355    //
   356    // When `active_request_bias == 0.0` the Least Request Load Balancer doesn't consider the number
   357    // of active requests at the time it picks a host and behaves like the Round Robin Load
   358    // Balancer.
   359    //
   360    // When `active_request_bias > 0.0` the Least Request Load Balancer scales the load balancing
   361    // weight by the number of active requests at the time it does a pick.
   362    //
   363    // The value is cached for performance reasons and refreshed whenever one of the Load Balancer's
   364    // host sets changes, e.g., whenever there is a host membership update or a host load balancing
   365    // weight change.
   366    //
   367    // .. note::
   368    //   This setting only takes effect if all host weights are not equal.
   369    core.v3.RuntimeDouble active_request_bias = 2;
   370  }
   371
   372  // Specific configuration for the :ref:`RingHash<arch_overview_load_balancing_types_ring_hash>`
   373  // load balancing policy.
   374  message RingHashLbConfig {
   375    option (udpa.annotations.versioning).previous_message_type =
   376        "envoy.api.v2.Cluster.RingHashLbConfig";
   377
   378    // The hash function used to hash hosts onto the ketama ring.
   379    enum HashFunction {
   380      // Use `xxHash <https://github.com/Cyan4973/xxHash>`_, this is the default hash function.
   381      XX_HASH = 0;
   382
   383      // Use `MurmurHash2 <https://sites.google.com/site/murmurhash/>`_, this is compatible with
   384      // std:hash<string> in GNU libstdc++ 3.4.20 or above. This is typically the case when compiled
   385      // on Linux and not macOS.
   386      MURMUR_HASH_2 = 1;
   387    }
   388
   389    reserved 2;
   390
   391    // Minimum hash ring size. The larger the ring is (that is, the more hashes there are for each
   392    // provided host) the better the request distribution will reflect the desired weights. Defaults
   393    // to 1024 entries, and limited to 8M entries. See also
   394    // :ref:`maximum_ring_size<envoy_api_field_config.cluster.v3.Cluster.RingHashLbConfig.maximum_ring_size>`.
   395    google.protobuf.UInt64Value minimum_ring_size = 1 [(validate.rules).uint64 = {lte: 8388608}];
   396
   397    // The hash function used to hash hosts onto the ketama ring. The value defaults to
   398    // :ref:`XX_HASH<envoy_api_enum_value_config.cluster.v3.Cluster.RingHashLbConfig.HashFunction.XX_HASH>`.
   399    HashFunction hash_function = 3 [(validate.rules).enum = {defined_only: true}];
   400
   401    // Maximum hash ring size. Defaults to 8M entries, and limited to 8M entries, but can be lowered
   402    // to further constrain resource use. See also
   403    // :ref:`minimum_ring_size<envoy_api_field_config.cluster.v3.Cluster.RingHashLbConfig.minimum_ring_size>`.
   404    google.protobuf.UInt64Value maximum_ring_size = 4 [(validate.rules).uint64 = {lte: 8388608}];
   405  }
   406
   407  // Specific configuration for the :ref:`Maglev<arch_overview_load_balancing_types_maglev>`
   408  // load balancing policy.
   409  message MaglevLbConfig {
   410    // The table size for Maglev hashing. The Maglev aims for ‘minimal disruption’ rather than an absolute guarantee.
   411    // Minimal disruption means that when the set of upstreams changes, a connection will likely be sent to the same
   412    // upstream as it was before. Increasing the table size reduces the amount of disruption.
   413    // The table size must be prime number. If it is not specified, the default is 65537.
   414    google.protobuf.UInt64Value table_size = 1;
   415  }
   416
   417  // Specific configuration for the
   418  // :ref:`Original Destination <arch_overview_load_balancing_types_original_destination>`
   419  // load balancing policy.
   420  message OriginalDstLbConfig {
   421    option (udpa.annotations.versioning).previous_message_type =
   422        "envoy.api.v2.Cluster.OriginalDstLbConfig";
   423
   424    // When true, :ref:`x-envoy-original-dst-host
   425    // <config_http_conn_man_headers_x-envoy-original-dst-host>` can be used to override destination
   426    // address.
   427    //
   428    // .. attention::
   429    //
   430    //   This header isn't sanitized by default, so enabling this feature allows HTTP clients to
   431    //   route traffic to arbitrary hosts and/or ports, which may have serious security
   432    //   consequences.
   433    //
   434    // .. note::
   435    //
   436    //   If the header appears multiple times only the first value is used.
   437    bool use_http_header = 1;
   438  }
   439
   440  // Common configuration for all load balancer implementations.
   441  // [#next-free-field: 8]
   442  message CommonLbConfig {
   443    option (udpa.annotations.versioning).previous_message_type =
   444        "envoy.api.v2.Cluster.CommonLbConfig";
   445
   446    // Configuration for :ref:`zone aware routing
   447    // <arch_overview_load_balancing_zone_aware_routing>`.
   448    message ZoneAwareLbConfig {
   449      option (udpa.annotations.versioning).previous_message_type =
   450          "envoy.api.v2.Cluster.CommonLbConfig.ZoneAwareLbConfig";
   451
   452      // Configures percentage of requests that will be considered for zone aware routing
   453      // if zone aware routing is configured. If not specified, the default is 100%.
   454      // * :ref:`runtime values <config_cluster_manager_cluster_runtime_zone_routing>`.
   455      // * :ref:`Zone aware routing support <arch_overview_load_balancing_zone_aware_routing>`.
   456      type.v3.Percent routing_enabled = 1;
   457
   458      // Configures minimum upstream cluster size required for zone aware routing
   459      // If upstream cluster size is less than specified, zone aware routing is not performed
   460      // even if zone aware routing is configured. If not specified, the default is 6.
   461      // * :ref:`runtime values <config_cluster_manager_cluster_runtime_zone_routing>`.
   462      // * :ref:`Zone aware routing support <arch_overview_load_balancing_zone_aware_routing>`.
   463      google.protobuf.UInt64Value min_cluster_size = 2;
   464
   465      // If set to true, Envoy will not consider any hosts when the cluster is in :ref:`panic
   466      // mode<arch_overview_load_balancing_panic_threshold>`. Instead, the cluster will fail all
   467      // requests as if all hosts are unhealthy. This can help avoid potentially overwhelming a
   468      // failing service.
   469      bool fail_traffic_on_panic = 3;
   470    }
   471
   472    // Configuration for :ref:`locality weighted load balancing
   473    // <arch_overview_load_balancing_locality_weighted_lb>`
   474    message LocalityWeightedLbConfig {
   475      option (udpa.annotations.versioning).previous_message_type =
   476          "envoy.api.v2.Cluster.CommonLbConfig.LocalityWeightedLbConfig";
   477    }
   478
   479    // Common Configuration for all consistent hashing load balancers (MaglevLb, RingHashLb, etc.)
   480    message ConsistentHashingLbConfig {
   481      option (udpa.annotations.versioning).previous_message_type =
   482          "envoy.api.v2.Cluster.CommonLbConfig.ConsistentHashingLbConfig";
   483
   484      // If set to `true`, the cluster will use hostname instead of the resolved
   485      // 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.
   486      bool use_hostname_for_hashing = 1;
   487
   488      // Configures percentage of average cluster load to bound per upstream host. For example, with a value of 150
   489      // no upstream host will get a load more than 1.5 times the average load of all the hosts in the cluster.
   490      // If not specified, the load is not bounded for any upstream host. Typical value for this parameter is between 120 and 200.
   491      // Minimum is 100.
   492      //
   493      // Applies to both Ring Hash and Maglev load balancers.
   494      //
   495      // This is implemented based on the method described in the paper https://arxiv.org/abs/1608.01350. For the specified
   496      // `hash_balance_factor`, requests to any upstream host are capped at `hash_balance_factor/100` times the average number of requests
   497      // across the cluster. When a request arrives for an upstream host that is currently serving at its max capacity, linear probing
   498      // is used to identify an eligible host. Further, the linear probe is implemented using a random jump in hosts ring/table to identify
   499      // the eligible host (this technique is as described in the paper https://arxiv.org/abs/1908.08762 - the random jump avoids the
   500      // cascading overflow effect when choosing the next host in the ring/table).
   501      //
   502      // If weights are specified on the hosts, they are respected.
   503      //
   504      // This is an O(N) algorithm, unlike other load balancers. Using a lower `hash_balance_factor` results in more hosts
   505      // being probed, so use a higher value if you require better performance.
   506      google.protobuf.UInt32Value hash_balance_factor = 2 [(validate.rules).uint32 = {gte: 100}];
   507    }
   508
   509    // Configures the :ref:`healthy panic threshold <arch_overview_load_balancing_panic_threshold>`.
   510    // If not specified, the default is 50%.
   511    // To disable panic mode, set to 0%.
   512    //
   513    // .. note::
   514    //   The specified percent will be truncated to the nearest 1%.
   515    type.v3.Percent healthy_panic_threshold = 1;
   516
   517    oneof locality_config_specifier {
   518      ZoneAwareLbConfig zone_aware_lb_config = 2;
   519
   520      LocalityWeightedLbConfig locality_weighted_lb_config = 3;
   521    }
   522
   523    // If set, all health check/weight/metadata updates that happen within this duration will be
   524    // merged and delivered in one shot when the duration expires. The start of the duration is when
   525    // the first update happens. This is useful for big clusters, with potentially noisy deploys
   526    // that might trigger excessive CPU usage due to a constant stream of healthcheck state changes
   527    // or metadata updates. The first set of updates to be seen apply immediately (e.g.: a new
   528    // cluster). Please always keep in mind that the use of sandbox technologies may change this
   529    // behavior.
   530    //
   531    // If this is not set, we default to a merge window of 1000ms. To disable it, set the merge
   532    // window to 0.
   533    //
   534    // Note: merging does not apply to cluster membership changes (e.g.: adds/removes); this is
   535    // because merging those updates isn't currently safe. See
   536    // https://github.com/envoyproxy/envoy/pull/3941.
   537    google.protobuf.Duration update_merge_window = 4;
   538
   539    // If set to true, Envoy will not consider new hosts when computing load balancing weights until
   540    // they have been health checked for the first time. This will have no effect unless
   541    // active health checking is also configured.
   542    //
   543    // Ignoring a host means that for any load balancing calculations that adjust weights based
   544    // on the ratio of eligible hosts and total hosts (priority spillover, locality weighting and
   545    // panic mode) Envoy will exclude these hosts in the denominator.
   546    //
   547    // For example, with hosts in two priorities P0 and P1, where P0 looks like
   548    // {healthy, unhealthy (new), unhealthy (new)}
   549    // and where P1 looks like
   550    // {healthy, healthy}
   551    // all traffic will still hit P0, as 1 / (3 - 2) = 1.
   552    //
   553    // Enabling this will allow scaling up the number of hosts for a given cluster without entering
   554    // panic mode or triggering priority spillover, assuming the hosts pass the first health check.
   555    //
   556    // If panic mode is triggered, new hosts are still eligible for traffic; they simply do not
   557    // contribute to the calculation when deciding whether panic mode is enabled or not.
   558    bool ignore_new_hosts_until_first_hc = 5;
   559
   560    // If set to `true`, the cluster manager will drain all existing
   561    // connections to upstream hosts whenever hosts are added or removed from the cluster.
   562    bool close_connections_on_host_set_change = 6;
   563
   564    // Common Configuration for all consistent hashing load balancers (MaglevLb, RingHashLb, etc.)
   565    ConsistentHashingLbConfig consistent_hashing_lb_config = 7;
   566  }
   567
   568  message RefreshRate {
   569    option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.Cluster.RefreshRate";
   570
   571    // Specifies the base interval between refreshes. This parameter is required and must be greater
   572    // than zero and less than
   573    // :ref:`max_interval <envoy_api_field_config.cluster.v3.Cluster.RefreshRate.max_interval>`.
   574    google.protobuf.Duration base_interval = 1 [(validate.rules).duration = {
   575      required: true
   576      gt {nanos: 1000000}
   577    }];
   578
   579    // Specifies the maximum interval between refreshes. This parameter is optional, but must be
   580    // greater than or equal to the
   581    // :ref:`base_interval <envoy_api_field_config.cluster.v3.Cluster.RefreshRate.base_interval>`  if set. The default
   582    // is 10 times the :ref:`base_interval <envoy_api_field_config.cluster.v3.Cluster.RefreshRate.base_interval>`.
   583    google.protobuf.Duration max_interval = 2 [(validate.rules).duration = {gt {nanos: 1000000}}];
   584  }
   585
   586  // [#not-implemented-hide:]
   587  message PreconnectPolicy {
   588    // Indicates how many streams (rounded up) can be anticipated per-upstream for each
   589    // incoming stream. This is useful for high-QPS or latency-sensitive services. Preconnecting
   590    // will only be done if the upstream is healthy.
   591    //
   592    // For example if this is 2, for an incoming HTTP/1.1 stream, 2 connections will be
   593    // established, one for the new incoming stream, and one for a presumed follow-up stream. For
   594    // HTTP/2, only one connection would be established by default as one connection can
   595    // serve both the original and presumed follow-up stream.
   596    //
   597    // In steady state for non-multiplexed connections a value of 1.5 would mean if there were 100
   598    // active streams, there would be 100 connections in use, and 50 connections preconnected.
   599    // This might be a useful value for something like short lived single-use connections,
   600    // for example proxying HTTP/1.1 if keep-alive were false and each stream resulted in connection
   601    // termination. It would likely be overkill for long lived connections, such as TCP proxying SMTP
   602    // or regular HTTP/1.1 with keep-alive. For long lived traffic, a value of 1.05 would be more
   603    // reasonable, where for every 100 connections, 5 preconnected connections would be in the queue
   604    // in case of unexpected disconnects where the connection could not be reused.
   605    //
   606    // If this value is not set, or set explicitly to one, Envoy will fetch as many connections
   607    // as needed to serve streams in flight. This means in steady state if a connection is torn down,
   608    // a subsequent streams will pay an upstream-rtt latency penalty waiting for streams to be
   609    // preconnected.
   610    //
   611    // This is limited somewhat arbitrarily to 3 because preconnecting too aggressively can
   612    // harm latency more than the preconnecting helps.
   613    google.protobuf.DoubleValue per_upstream_preconnect_ratio = 1
   614        [(validate.rules).double = {lte: 3.0 gte: 1.0}];
   615
   616    // Indicates how many many streams (rounded up) can be anticipated across a cluster for each
   617    // stream, useful for low QPS services. This is currently supported for a subset of
   618    // deterministic non-hash-based load-balancing algorithms (weighted round robin, random).
   619    // Unlike per_upstream_preconnect_ratio this preconnects across the upstream instances in a
   620    // cluster, doing best effort predictions of what upstream would be picked next and
   621    // pre-establishing a connection.
   622    //
   623    // For example if preconnecting is set to 2 for a round robin HTTP/2 cluster, on the first
   624    // incoming stream, 2 connections will be preconnected - one to the first upstream for this
   625    // cluster, one to the second on the assumption there will be a follow-up stream.
   626    //
   627    // Preconnecting will be limited to one preconnect per configured upstream in the cluster.
   628    //
   629    // If this value is not set, or set explicitly to one, Envoy will fetch as many connections
   630    // as needed to serve streams in flight, so during warm up and in steady state if a connection
   631    // is closed (and per_upstream_preconnect_ratio is not set), there will be a latency hit for
   632    // connection establishment.
   633    //
   634    // If both this and preconnect_ratio are set, Envoy will make sure both predicted needs are met,
   635    // basically preconnecting max(predictive-preconnect, per-upstream-preconnect), for each upstream.
   636    // TODO(alyssawilk) per LB docs and LB overview docs when unhiding.
   637    google.protobuf.DoubleValue predictive_preconnect_ratio = 2
   638        [(validate.rules).double = {lte: 3.0 gte: 1.0}];
   639  }
   640
   641  reserved 12, 15, 7, 11, 35;
   642
   643  reserved "hosts", "tls_context", "extension_protocol_options";
   644
   645  // Configuration to use different transport sockets for different endpoints.
   646  // The entry of *envoy.transport_socket_match* in the
   647  // :ref:`LbEndpoint.Metadata <envoy_api_field_config.endpoint.v3.LbEndpoint.metadata>`
   648  // is used to match against the transport sockets as they appear in the list. The first
   649  // :ref:`match <envoy_api_msg_config.cluster.v3.Cluster.TransportSocketMatch>` is used.
   650  // For example, with the following match
   651  //
   652  // .. code-block:: yaml
   653  //
   654  //  transport_socket_matches:
   655  //  - name: "enableMTLS"
   656  //    match:
   657  //      acceptMTLS: true
   658  //    transport_socket:
   659  //      name: envoy.transport_sockets.tls
   660  //      config: { ... } # tls socket configuration
   661  //  - name: "defaultToPlaintext"
   662  //    match: {}
   663  //    transport_socket:
   664  //      name: envoy.transport_sockets.raw_buffer
   665  //
   666  // Connections to the endpoints whose metadata value under *envoy.transport_socket_match*
   667  // having "acceptMTLS"/"true" key/value pair use the "enableMTLS" socket configuration.
   668  //
   669  // If a :ref:`socket match <envoy_api_msg_config.cluster.v3.Cluster.TransportSocketMatch>` with empty match
   670  // criteria is provided, that always match any endpoint. For example, the "defaultToPlaintext"
   671  // socket match in case above.
   672  //
   673  // If an endpoint metadata's value under *envoy.transport_socket_match* does not match any
   674  // *TransportSocketMatch*, socket configuration fallbacks to use the *tls_context* or
   675  // *transport_socket* specified in this cluster.
   676  //
   677  // This field allows gradual and flexible transport socket configuration changes.
   678  //
   679  // The metadata of endpoints in EDS can indicate transport socket capabilities. For example,
   680  // an endpoint's metadata can have two key value pairs as "acceptMTLS": "true",
   681  // "acceptPlaintext": "true". While some other endpoints, only accepting plaintext traffic
   682  // has "acceptPlaintext": "true" metadata information.
   683  //
   684  // Then the xDS server can configure the CDS to a client, Envoy A, to send mutual TLS
   685  // traffic for endpoints with "acceptMTLS": "true", by adding a corresponding
   686  // *TransportSocketMatch* in this field. Other client Envoys receive CDS without
   687  // *transport_socket_match* set, and still send plain text traffic to the same cluster.
   688  //
   689  // This field can be used to specify custom transport socket configurations for health
   690  // checks by adding matching key/value pairs in a health check's
   691  // :ref:`transport socket match criteria <envoy_api_field_config.core.v3.HealthCheck.transport_socket_match_criteria>` field.
   692  //
   693  // [#comment:TODO(incfly): add a detailed architecture doc on intended usage.]
   694  repeated TransportSocketMatch transport_socket_matches = 43;
   695
   696  // Supplies the name of the cluster which must be unique across all clusters.
   697  // The cluster name is used when emitting
   698  // :ref:`statistics <config_cluster_manager_cluster_stats>` if :ref:`alt_stat_name
   699  // <envoy_api_field_config.cluster.v3.Cluster.alt_stat_name>` is not provided.
   700  // Any ``:`` in the cluster name will be converted to ``_`` when emitting statistics.
   701  string name = 1 [(validate.rules).string = {min_len: 1}];
   702
   703  // An optional alternative to the cluster name to be used while emitting stats.
   704  // Any ``:`` in the name will be converted to ``_`` when emitting statistics. This should not be
   705  // confused with :ref:`Router Filter Header
   706  // <config_http_filters_router_x-envoy-upstream-alt-stat-name>`.
   707  string alt_stat_name = 28;
   708
   709  oneof cluster_discovery_type {
   710    // The :ref:`service discovery type <arch_overview_service_discovery_types>`
   711    // to use for resolving the cluster.
   712    DiscoveryType type = 2 [(validate.rules).enum = {defined_only: true}];
   713
   714    // The custom cluster type.
   715    CustomClusterType cluster_type = 38;
   716  }
   717
   718  // Configuration to use for EDS updates for the Cluster.
   719  EdsClusterConfig eds_cluster_config = 3;
   720
   721  // The timeout for new network connections to hosts in the cluster.
   722  google.protobuf.Duration connect_timeout = 4 [(validate.rules).duration = {gt {}}];
   723
   724  // Soft limit on size of the cluster’s connections read and write buffers. If
   725  // unspecified, an implementation defined default is applied (1MiB).
   726  google.protobuf.UInt32Value per_connection_buffer_limit_bytes = 5
   727      [(udpa.annotations.security).configure_for_untrusted_upstream = true];
   728
   729  // The :ref:`load balancer type <arch_overview_load_balancing_types>` to use
   730  // when picking a host in the cluster.
   731  // [#comment:TODO: Remove enum constraint :ref:`LOAD_BALANCING_POLICY_CONFIG<envoy_api_enum_value_config.cluster.v3.Cluster.LbPolicy.LOAD_BALANCING_POLICY_CONFIG>` when implemented.]
   732  LbPolicy lb_policy = 6 [(validate.rules).enum = {defined_only: true not_in: 7}];
   733
   734  // Setting this is required for specifying members of
   735  // :ref:`STATIC<envoy_api_enum_value_config.cluster.v3.Cluster.DiscoveryType.STATIC>`,
   736  // :ref:`STRICT_DNS<envoy_api_enum_value_config.cluster.v3.Cluster.DiscoveryType.STRICT_DNS>`
   737  // or :ref:`LOGICAL_DNS<envoy_api_enum_value_config.cluster.v3.Cluster.DiscoveryType.LOGICAL_DNS>` clusters.
   738  // This field supersedes the *hosts* field in the v2 API.
   739  //
   740  // .. attention::
   741  //
   742  //   Setting this allows non-EDS cluster types to contain embedded EDS equivalent
   743  //   :ref:`endpoint assignments<envoy_api_msg_config.endpoint.v3.ClusterLoadAssignment>`.
   744  //
   745  endpoint.v3.ClusterLoadAssignment load_assignment = 33;
   746
   747  // Optional :ref:`active health checking <arch_overview_health_checking>`
   748  // configuration for the cluster. If no
   749  // configuration is specified no health checking will be done and all cluster
   750  // members will be considered healthy at all times.
   751  repeated core.v3.HealthCheck health_checks = 8;
   752
   753  // Optional maximum requests for a single upstream connection. This parameter
   754  // is respected by both the HTTP/1.1 and HTTP/2 connection pool
   755  // implementations. If not specified, there is no limit. Setting this
   756  // parameter to 1 will effectively disable keep alive.
   757  google.protobuf.UInt32Value max_requests_per_connection = 9;
   758
   759  // Optional :ref:`circuit breaking <arch_overview_circuit_break>` for the cluster.
   760  CircuitBreakers circuit_breakers = 10;
   761
   762  // HTTP protocol options that are applied only to upstream HTTP connections.
   763  // These options apply to all HTTP versions.
   764  // This has been deprecated in favor of
   765  // :ref:`upstream_http_protocol_options <envoy_api_field_extensions.upstreams.http.v3.HttpProtocolOptions.upstream_http_protocol_options>`
   766  // in the :ref:`http_protocol_options <envoy_api_msg_extensions.upstreams.http.v3.HttpProtocolOptions>` message.
   767  // upstream_http_protocol_options can be set via the cluster's
   768  // :ref:`extension_protocol_options<envoy_api_field_config.cluster.v3.Cluster.typed_extension_protocol_options>`.
   769  // See ref:`upstream_http_protocol_options
   770  // <envoy_api_field_extensions.upstreams.http.v3.HttpProtocolOptions.upstream_http_protocol_options>`
   771  // for example usage.
   772  core.v3.UpstreamHttpProtocolOptions upstream_http_protocol_options = 46 [deprecated = true];
   773
   774  // Additional options when handling HTTP requests upstream. These options will be applicable to
   775  // both HTTP1 and HTTP2 requests.
   776  // This has been deprecated in favor of
   777  // :ref:`common_http_protocol_options <envoy_api_field_extensions.upstreams.http.v3.HttpProtocolOptions.common_http_protocol_options>`
   778  // in the :ref:`http_protocol_options <envoy_api_msg_extensions.upstreams.http.v3.HttpProtocolOptions>` message.
   779  // common_http_protocol_options can be set via the cluster's
   780  // :ref:`extension_protocol_options<envoy_api_field_config.cluster.v3.Cluster.typed_extension_protocol_options>`.
   781  // See ref:`upstream_http_protocol_options
   782  // <envoy_api_field_extensions.upstreams.http.v3.HttpProtocolOptions.upstream_http_protocol_options>`
   783  // for example usage.
   784  core.v3.HttpProtocolOptions common_http_protocol_options = 29 [deprecated = true];
   785
   786  // Additional options when handling HTTP1 requests.
   787  // This has been deprecated in favor of http_protocol_options fields in the in the
   788  // :ref:`http_protocol_options <envoy_api_msg_extensions.upstreams.http.v3.HttpProtocolOptions>` message.
   789  // http_protocol_options can be set via the cluster's
   790  // :ref:`extension_protocol_options<envoy_api_field_config.cluster.v3.Cluster.typed_extension_protocol_options>`.
   791  // See ref:`upstream_http_protocol_options
   792  // <envoy_api_field_extensions.upstreams.http.v3.HttpProtocolOptions.upstream_http_protocol_options>`
   793  // for example usage.
   794  core.v3.Http1ProtocolOptions http_protocol_options = 13 [deprecated = true];
   795
   796  // Even if default HTTP2 protocol options are desired, this field must be
   797  // set so that Envoy will assume that the upstream supports HTTP/2 when
   798  // making new HTTP connection pool connections. Currently, Envoy only
   799  // supports prior knowledge for upstream connections. Even if TLS is used
   800  // with ALPN, `http2_protocol_options` must be specified. As an aside this allows HTTP/2
   801  // connections to happen over plain text.
   802  // This has been deprecated in favor of http2_protocol_options fields in the in the
   803  // :ref:`http_protocol_options <envoy_api_msg_extensions.upstreams.http.v3.HttpProtocolOptions>`
   804  // message. http2_protocol_options can be set via the cluster's
   805  // :ref:`extension_protocol_options<envoy_api_field_config.cluster.v3.Cluster.typed_extension_protocol_options>`.
   806  // See ref:`upstream_http_protocol_options
   807  // <envoy_api_field_extensions.upstreams.http.v3.HttpProtocolOptions.upstream_http_protocol_options>`
   808  // for example usage.
   809  core.v3.Http2ProtocolOptions http2_protocol_options = 14
   810      [deprecated = true, (udpa.annotations.security).configure_for_untrusted_upstream = true];
   811
   812  // The extension_protocol_options field is used to provide extension-specific protocol options
   813  // for upstream connections. The key should match the extension filter name, such as
   814  // "envoy.filters.network.thrift_proxy". See the extension's documentation for details on
   815  // specific options.
   816  // [#next-major-version: make this a list of typed extensions.]
   817  map<string, google.protobuf.Any> typed_extension_protocol_options = 36;
   818
   819  // If the DNS refresh rate is specified and the cluster type is either
   820  // :ref:`STRICT_DNS<envoy_api_enum_value_config.cluster.v3.Cluster.DiscoveryType.STRICT_DNS>`,
   821  // or :ref:`LOGICAL_DNS<envoy_api_enum_value_config.cluster.v3.Cluster.DiscoveryType.LOGICAL_DNS>`,
   822  // this value is used as the cluster’s DNS refresh
   823  // rate. The value configured must be at least 1ms. If this setting is not specified, the
   824  // value defaults to 5000ms. For cluster types other than
   825  // :ref:`STRICT_DNS<envoy_api_enum_value_config.cluster.v3.Cluster.DiscoveryType.STRICT_DNS>`
   826  // and :ref:`LOGICAL_DNS<envoy_api_enum_value_config.cluster.v3.Cluster.DiscoveryType.LOGICAL_DNS>`
   827  // this setting is ignored.
   828  google.protobuf.Duration dns_refresh_rate = 16
   829      [(validate.rules).duration = {gt {nanos: 1000000}}];
   830
   831  // If the DNS failure refresh rate is specified and the cluster type is either
   832  // :ref:`STRICT_DNS<envoy_api_enum_value_config.cluster.v3.Cluster.DiscoveryType.STRICT_DNS>`,
   833  // or :ref:`LOGICAL_DNS<envoy_api_enum_value_config.cluster.v3.Cluster.DiscoveryType.LOGICAL_DNS>`,
   834  // this is used as the cluster’s DNS refresh rate when requests are failing. If this setting is
   835  // not specified, the failure refresh rate defaults to the DNS refresh rate. For cluster types
   836  // other than :ref:`STRICT_DNS<envoy_api_enum_value_config.cluster.v3.Cluster.DiscoveryType.STRICT_DNS>` and
   837  // :ref:`LOGICAL_DNS<envoy_api_enum_value_config.cluster.v3.Cluster.DiscoveryType.LOGICAL_DNS>` this setting is
   838  // ignored.
   839  RefreshRate dns_failure_refresh_rate = 44;
   840
   841  // Optional configuration for setting cluster's DNS refresh rate. If the value is set to true,
   842  // cluster's DNS refresh rate will be set to resource record's TTL which comes from DNS
   843  // resolution.
   844  bool respect_dns_ttl = 39;
   845
   846  // The DNS IP address resolution policy. If this setting is not specified, the
   847  // value defaults to
   848  // :ref:`AUTO<envoy_api_enum_value_config.cluster.v3.Cluster.DnsLookupFamily.AUTO>`.
   849  DnsLookupFamily dns_lookup_family = 17 [(validate.rules).enum = {defined_only: true}];
   850
   851  // If DNS resolvers are specified and the cluster type is either
   852  // :ref:`STRICT_DNS<envoy_api_enum_value_config.cluster.v3.Cluster.DiscoveryType.STRICT_DNS>`,
   853  // or :ref:`LOGICAL_DNS<envoy_api_enum_value_config.cluster.v3.Cluster.DiscoveryType.LOGICAL_DNS>`,
   854  // this value is used to specify the cluster’s dns resolvers.
   855  // If this setting is not specified, the value defaults to the default
   856  // resolver, which uses /etc/resolv.conf for configuration. For cluster types
   857  // other than
   858  // :ref:`STRICT_DNS<envoy_api_enum_value_config.cluster.v3.Cluster.DiscoveryType.STRICT_DNS>`
   859  // and :ref:`LOGICAL_DNS<envoy_api_enum_value_config.cluster.v3.Cluster.DiscoveryType.LOGICAL_DNS>`
   860  // this setting is ignored.
   861  // Setting this value causes failure if the
   862  // ``envoy.restart_features.use_apple_api_for_dns_lookups`` runtime value is true during
   863  // server startup. Apple's API only allows overriding DNS resolvers via system settings.
   864  repeated core.v3.Address dns_resolvers = 18;
   865
   866  // [#next-major-version: Reconcile DNS options in a single message.]
   867  // Always use TCP queries instead of UDP queries for DNS lookups.
   868  // Setting this value causes failure if the
   869  // ``envoy.restart_features.use_apple_api_for_dns_lookups`` runtime value is true during
   870  // server startup. Apple' API only uses UDP for DNS resolution.
   871  bool use_tcp_for_dns_lookups = 45;
   872
   873  // If specified, outlier detection will be enabled for this upstream cluster.
   874  // Each of the configuration values can be overridden via
   875  // :ref:`runtime values <config_cluster_manager_cluster_runtime_outlier_detection>`.
   876  OutlierDetection outlier_detection = 19;
   877
   878  // The interval for removing stale hosts from a cluster type
   879  // :ref:`ORIGINAL_DST<envoy_api_enum_value_config.cluster.v3.Cluster.DiscoveryType.ORIGINAL_DST>`.
   880  // Hosts are considered stale if they have not been used
   881  // as upstream destinations during this interval. New hosts are added
   882  // to original destination clusters on demand as new connections are
   883  // redirected to Envoy, causing the number of hosts in the cluster to
   884  // grow over time. Hosts that are not stale (they are actively used as
   885  // destinations) are kept in the cluster, which allows connections to
   886  // them remain open, saving the latency that would otherwise be spent
   887  // on opening new connections. If this setting is not specified, the
   888  // value defaults to 5000ms. For cluster types other than
   889  // :ref:`ORIGINAL_DST<envoy_api_enum_value_config.cluster.v3.Cluster.DiscoveryType.ORIGINAL_DST>`
   890  // this setting is ignored.
   891  google.protobuf.Duration cleanup_interval = 20 [(validate.rules).duration = {gt {}}];
   892
   893  // Optional configuration used to bind newly established upstream connections.
   894  // This overrides any bind_config specified in the bootstrap proto.
   895  // If the address and port are empty, no bind will be performed.
   896  core.v3.BindConfig upstream_bind_config = 21;
   897
   898  // Configuration for load balancing subsetting.
   899  LbSubsetConfig lb_subset_config = 22;
   900
   901  // Optional configuration for the load balancing algorithm selected by
   902  // LbPolicy. Currently only
   903  // :ref:`RING_HASH<envoy_api_enum_value_config.cluster.v3.Cluster.LbPolicy.RING_HASH>`,
   904  // :ref:`MAGLEV<envoy_api_enum_value_config.cluster.v3.Cluster.LbPolicy.MAGLEV>` and
   905  // :ref:`LEAST_REQUEST<envoy_api_enum_value_config.cluster.v3.Cluster.LbPolicy.LEAST_REQUEST>`
   906  // has additional configuration options.
   907  // Specifying ring_hash_lb_config or maglev_lb_config or least_request_lb_config without setting the corresponding
   908  // LbPolicy will generate an error at runtime.
   909  oneof lb_config {
   910    // Optional configuration for the Ring Hash load balancing policy.
   911    RingHashLbConfig ring_hash_lb_config = 23;
   912
   913    // Optional configuration for the Maglev load balancing policy.
   914    MaglevLbConfig maglev_lb_config = 52;
   915
   916    // Optional configuration for the Original Destination load balancing policy.
   917    OriginalDstLbConfig original_dst_lb_config = 34;
   918
   919    // Optional configuration for the LeastRequest load balancing policy.
   920    LeastRequestLbConfig least_request_lb_config = 37;
   921  }
   922
   923  // Common configuration for all load balancer implementations.
   924  CommonLbConfig common_lb_config = 27;
   925
   926  // Optional custom transport socket implementation to use for upstream connections.
   927  // To setup TLS, set a transport socket with name `tls` and
   928  // :ref:`UpstreamTlsContexts <envoy_api_msg_extensions.transport_sockets.tls.v3.UpstreamTlsContext>` in the `typed_config`.
   929  // If no transport socket configuration is specified, new connections
   930  // will be set up with plaintext.
   931  core.v3.TransportSocket transport_socket = 24;
   932
   933  // The Metadata field can be used to provide additional information about the
   934  // cluster. It can be used for stats, logging, and varying filter behavior.
   935  // Fields should use reverse DNS notation to denote which entity within Envoy
   936  // will need the information. For instance, if the metadata is intended for
   937  // the Router filter, the filter name should be specified as *envoy.filters.http.router*.
   938  core.v3.Metadata metadata = 25;
   939
   940  // Determines how Envoy selects the protocol used to speak to upstream hosts.
   941  // This has been deprecated in favor of setting explicit protocol selection
   942  // in the :ref:`http_protocol_options
   943  // <envoy_api_msg_extensions.upstreams.http.v3.HttpProtocolOptions>` message.
   944  // http_protocol_options can be set via the cluster's
   945  // :ref:`extension_protocol_options<envoy_api_field_config.cluster.v3.Cluster.typed_extension_protocol_options>`.
   946  ClusterProtocolSelection protocol_selection = 26 [deprecated = true];
   947
   948  // Optional options for upstream connections.
   949  UpstreamConnectionOptions upstream_connection_options = 30;
   950
   951  // If an upstream host becomes unhealthy (as determined by the configured health checks
   952  // or outlier detection), immediately close all connections to the failed host.
   953  //
   954  // .. note::
   955  //
   956  //   This is currently only supported for connections created by tcp_proxy.
   957  //
   958  // .. note::
   959  //
   960  //   The current implementation of this feature closes all connections immediately when
   961  //   the unhealthy status is detected. If there are a large number of connections open
   962  //   to an upstream host that becomes unhealthy, Envoy may spend a substantial amount of
   963  //   time exclusively closing these connections, and not processing any other traffic.
   964  bool close_connections_on_host_health_failure = 31;
   965
   966  // If set to true, Envoy will ignore the health value of a host when processing its removal
   967  // from service discovery. This means that if active health checking is used, Envoy will *not*
   968  // wait for the endpoint to go unhealthy before removing it.
   969  bool ignore_health_on_host_removal = 32;
   970
   971  // An (optional) network filter chain, listed in the order the filters should be applied.
   972  // The chain will be applied to all outgoing connections that Envoy makes to the upstream
   973  // servers of this cluster.
   974  repeated Filter filters = 40;
   975
   976  // [#not-implemented-hide:] New mechanism for LB policy configuration. Used only if the
   977  // :ref:`lb_policy<envoy_api_field_config.cluster.v3.Cluster.lb_policy>` field has the value
   978  // :ref:`LOAD_BALANCING_POLICY_CONFIG<envoy_api_enum_value_config.cluster.v3.Cluster.LbPolicy.LOAD_BALANCING_POLICY_CONFIG>`.
   979  LoadBalancingPolicy load_balancing_policy = 41;
   980
   981  // [#not-implemented-hide:]
   982  // If present, tells the client where to send load reports via LRS. If not present, the
   983  // client will fall back to a client-side default, which may be either (a) don't send any
   984  // load reports or (b) send load reports for all clusters to a single default server
   985  // (which may be configured in the bootstrap file).
   986  //
   987  // Note that if multiple clusters point to the same LRS server, the client may choose to
   988  // create a separate stream for each cluster or it may choose to coalesce the data for
   989  // multiple clusters onto a single stream. Either way, the client must make sure to send
   990  // the data for any given cluster on no more than one stream.
   991  //
   992  // [#next-major-version: In the v3 API, we should consider restructuring this somehow,
   993  // maybe by allowing LRS to go on the ADS stream, or maybe by moving some of the negotiation
   994  // from the LRS stream here.]
   995  core.v3.ConfigSource lrs_server = 42;
   996
   997  // If track_timeout_budgets is true, the :ref:`timeout budget histograms
   998  // <config_cluster_manager_cluster_stats_timeout_budgets>` will be published for each
   999  // request. These show what percentage of a request's per try and global timeout was used. A value
  1000  // of 0 would indicate that none of the timeout was used or that the timeout was infinite. A value
  1001  // of 100 would indicate that the request took the entirety of the timeout given to it.
  1002  //
  1003  // .. attention::
  1004  //
  1005  //   This field has been deprecated in favor of `timeout_budgets`, part of
  1006  //   :ref:`track_cluster_stats <envoy_api_field_config.cluster.v3.Cluster.track_cluster_stats>`.
  1007  bool track_timeout_budgets = 47 [deprecated = true];
  1008
  1009  // Optional customization and configuration of upstream connection pool, and upstream type.
  1010  //
  1011  // Currently this field only applies for HTTP traffic but is designed for eventual use for custom
  1012  // TCP upstreams.
  1013  //
  1014  // For HTTP traffic, Envoy will generally take downstream HTTP and send it upstream as upstream
  1015  // HTTP, using the http connection pool and the codec from `http2_protocol_options`
  1016  //
  1017  // For routes where CONNECT termination is configured, Envoy will take downstream CONNECT
  1018  // requests and forward the CONNECT payload upstream over raw TCP using the tcp connection pool.
  1019  //
  1020  // The default pool used is the generic connection pool which creates the HTTP upstream for most
  1021  // HTTP requests, and the TCP upstream if CONNECT termination is configured.
  1022  //
  1023  // If users desire custom connection pool or upstream behavior, for example terminating
  1024  // CONNECT only if a custom filter indicates it is appropriate, the custom factories
  1025  // can be registered and configured here.
  1026  core.v3.TypedExtensionConfig upstream_config = 48;
  1027
  1028  // Configuration to track optional cluster stats.
  1029  TrackClusterStats track_cluster_stats = 49;
  1030
  1031  // [#not-implemented-hide:]
  1032  // Preconnect configuration for this cluster.
  1033  PreconnectPolicy preconnect_policy = 50;
  1034
  1035  // If `connection_pool_per_downstream_connection` is true, the cluster will use a separate
  1036  // connection pool for every downstream connection
  1037  bool connection_pool_per_downstream_connection = 51;
  1038}
  1039
  1040// [#not-implemented-hide:] Extensible load balancing policy configuration.
  1041//
  1042// Every LB policy defined via this mechanism will be identified via a unique name using reverse
  1043// DNS notation. If the policy needs configuration parameters, it must define a message for its
  1044// own configuration, which will be stored in the config field. The name of the policy will tell
  1045// clients which type of message they should expect to see in the config field.
  1046//
  1047// Note that there are cases where it is useful to be able to independently select LB policies
  1048// for choosing a locality and for choosing an endpoint within that locality. For example, a
  1049// given deployment may always use the same policy to choose the locality, but for choosing the
  1050// endpoint within the locality, some clusters may use weighted-round-robin, while others may
  1051// use some sort of session-based balancing.
  1052//
  1053// This can be accomplished via hierarchical LB policies, where the parent LB policy creates a
  1054// child LB policy for each locality. For each request, the parent chooses the locality and then
  1055// delegates to the child policy for that locality to choose the endpoint within the locality.
  1056//
  1057// To facilitate this, the config message for the top-level LB policy may include a field of
  1058// type LoadBalancingPolicy that specifies the child policy.
  1059message LoadBalancingPolicy {
  1060  option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.LoadBalancingPolicy";
  1061
  1062  message Policy {
  1063    option (udpa.annotations.versioning).previous_message_type =
  1064        "envoy.api.v2.LoadBalancingPolicy.Policy";
  1065
  1066    reserved 2;
  1067
  1068    reserved "config";
  1069
  1070    // Required. The name of the LB policy.
  1071    string name = 1;
  1072
  1073    google.protobuf.Any typed_config = 3;
  1074  }
  1075
  1076  // Each client will iterate over the list in order and stop at the first policy that it
  1077  // supports. This provides a mechanism for starting to use new LB policies that are not yet
  1078  // supported by all clients.
  1079  repeated Policy policies = 1;
  1080}
  1081
  1082// An extensible structure containing the address Envoy should bind to when
  1083// establishing upstream connections.
  1084message UpstreamBindConfig {
  1085  option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.UpstreamBindConfig";
  1086
  1087  // The address Envoy should bind to when establishing upstream connections.
  1088  core.v3.Address source_address = 1;
  1089}
  1090
  1091message UpstreamConnectionOptions {
  1092  option (udpa.annotations.versioning).previous_message_type =
  1093      "envoy.api.v2.UpstreamConnectionOptions";
  1094
  1095  // If set then set SO_KEEPALIVE on the socket to enable TCP Keepalives.
  1096  core.v3.TcpKeepalive tcp_keepalive = 1;
  1097}
  1098
  1099message TrackClusterStats {
  1100  // If timeout_budgets is true, the :ref:`timeout budget histograms
  1101  // <config_cluster_manager_cluster_stats_timeout_budgets>` will be published for each
  1102  // request. These show what percentage of a request's per try and global timeout was used. A value
  1103  // of 0 would indicate that none of the timeout was used or that the timeout was infinite. A value
  1104  // of 100 would indicate that the request took the entirety of the timeout given to it.
  1105  bool timeout_budgets = 1;
  1106
  1107  // If request_response_sizes is true, then the :ref:`histograms
  1108  // <config_cluster_manager_cluster_stats_request_response_sizes>`  tracking header and body sizes
  1109  // of requests and responses will be published.
  1110  bool request_response_sizes = 2;
  1111}

View as plain text