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