Clusters

Cluster

[Cluster proto]

Configuration for a single upstream cluster.

  1. {
  2.   "name": "...",
  3.   "alt_stat_name": "...",
  4.   "type": "...",
  5.   "eds_cluster_config": "{...}",
  6.   "connect_timeout": "{...}",
  7.   "per_connection_buffer_limit_bytes": "{...}",
  8.   "lb_policy": "...",
  9.   "hosts": [],
  10.   "health_checks": [],
  11.   "max_requests_per_connection": "{...}",
  12.   "circuit_breakers": "{...}",
  13.   "tls_context": "{...}",
  14.   "common_http_protocol_options": "{...}",
  15.   "http_protocol_options": "{...}",
  16.   "http2_protocol_options": "{...}",
  17.   "dns_refresh_rate": "{...}",
  18.   "dns_lookup_family": "...",
  19.   "dns_resolvers": [],
  20.   "outlier_detection": "{...}",
  21.   "cleanup_interval": "{...}",
  22.   "upstream_bind_config": "{...}",
  23.   "lb_subset_config": "{...}",
  24.   "ring_hash_lb_config": "{...}",
  25.   "common_lb_config": "{...}",
  26.   "transport_socket": "{...}",
  27.   "metadata": "{...}",
  28.   "protocol_selection": "..."
  29. }

name

(string, REQUIRED) Supplies the name of the cluster which must be unique across all clusters. The cluster name is used when emitting statistics if alt_stat_name is not provided. Any : in the cluster name will be converted to _ when emitting statistics. By default, the maximum length of a cluster name is limited to 60 characters. This limit can be increased by setting the --max-obj-name-len command line argument to the desired value.

alt_stat_name

(string) An optional alternative to the cluster name to be used while emitting stats. Any : in the name will be converted to _ when emitting statistics. This should not be confused with Router Filter Header.

type

(Cluster.DiscoveryType) The service discovery type to use for resolving the cluster.

eds_cluster_config

(Cluster.EdsClusterConfig) Configuration to use for EDS updates for the Cluster.

connect_timeout

(Duration) The timeout for new network connections to hosts in the cluster.

per_connection_buffer_limit_bytes

(UInt32Value) Soft limit on size of the cluster’s connections read and write buffers. If unspecified, an implementation defined default is applied (1MiB).

lb_policy

(Cluster.LbPolicy) The load balancer type to use when picking a host in the cluster.

hosts

(core.Address) If the service discovery type is STATIC, STRICT_DNS or LOGICAL_DNS, then hosts is required.

health_checks

(core.HealthCheck) Optional active health checking configuration for the cluster. If no configuration is specified no health checking will be done and all cluster members will be considered healthy at all times.

max_requests_per_connection

(UInt32Value) Optional maximum requests for a single upstream connection. This parameter is respected by both the HTTP/1.1 and HTTP/2 connection pool implementations. If not specified, there is no limit. Setting this parameter to 1 will effectively disable keep alive.

circuit_breakers

(cluster.CircuitBreakers) Optional circuit breaking for the cluster.

tls_context

(auth.UpstreamTlsContext) The TLS configuration for connections to the upstream cluster. If no TLS configuration is specified, TLS will not be used for new connections.

Attention

Server certificate verification is not enabled by default. Configure trusted_ca to enable verification.

common_http_protocol_options

(core.HttpProtocolOptions) Additional options when handling HTTP requests. These options will be applicable to both HTTP1 and HTTP2 requests.

http_protocol_options

(core.Http1ProtocolOptions) Additional options when handling HTTP1 requests.

http2_protocol_options

(core.Http2ProtocolOptions) Even if default HTTP2 protocol options are desired, this field must be set so that Envoy will assume that the upstream supports HTTP/2 when making new HTTP connection pool connections. Currently, Envoy only supports prior knowledge for upstream connections. Even if TLS is used with ALPN, http2_protocol_options must be specified. As an aside this allows HTTP/2 connections to happen over plain text.

dns_refresh_rate

(Duration) If the DNS refresh rate is specified and the cluster type is either STRICT_DNS, or LOGICAL_DNS, this value is used as the cluster’s DNS refresh rate. If this setting is not specified, the value defaults to 5000. For cluster types other than STRICT_DNS and LOGICAL_DNS this setting is ignored.

dns_lookup_family

(Cluster.DnsLookupFamily) The DNS IP address resolution policy. If this setting is not specified, the value defaults to AUTO.

dns_resolvers

(core.Address) If DNS resolvers are specified and the cluster type is either STRICT_DNS, or LOGICAL_DNS, this value is used to specify the cluster’s dns resolvers. If this setting is not specified, the value defaults to the default resolver, which uses /etc/resolv.conf for configuration. For cluster types other than STRICT_DNS and LOGICAL_DNS this setting is ignored.

outlier_detection

(cluster.OutlierDetection) If specified, outlier detection will be enabled for this upstream cluster. Each of the configuration values can be overridden via runtime values.

cleanup_interval

(Duration) The interval for removing stale hosts from a cluster type ORIGINAL_DST. Hosts are considered stale if they have not been used as upstream destinations during this interval. New hosts are added to original destination clusters on demand as new connections are redirected to Envoy, causing the number of hosts in the cluster to grow over time. Hosts that are not stale (they are actively used as destinations) are kept in the cluster, which allows connections to them remain open, saving the latency that would otherwise be spent on opening new connections. If this setting is not specified, the value defaults to 5000ms. For cluster types other than ORIGINAL_DST this setting is ignored.

upstream_bind_config

(core.BindConfig) Optional configuration used to bind newly established upstream connections. This overrides any bind_config specified in the bootstrap proto. If the address and port are empty, no bind will be performed.

lb_subset_config

(Cluster.LbSubsetConfig) Configuration for load balancing subsetting.

ring_hash_lb_config

(Cluster.RingHashLbConfig) Optional configuration for the Ring Hash load balancing policy.

Only one of ring_hash_lb_config may be set.

common_lb_config

(Cluster.CommonLbConfig) Common configuration for all load balancer implementations.

transport_socket

(core.TransportSocket) Optional custom transport socket implementation to use for upstream connections.

metadata

(core.Metadata) The Metadata field can be used to provide additional information about the cluster. It can be used for stats, logging, and varying filter behavior. Fields should use reverse DNS notation to denote which entity within Envoy will need the information. For instance, if the metadata is intended for the Router filter, the filter name should be specified as envoy.router.

protocol_selection

(Cluster.ClusterProtocolSelection) Determines how Envoy selects the protocol used to speak to upstream hosts.

Cluster.EdsClusterConfig

[Cluster.EdsClusterConfig proto]

Only valid when discovery type is EDS.

  1. {
  2.   "eds_config": "{...}",
  3.   "service_name": "..."
  4. }

eds_config

(core.ConfigSource) Configuration for the source of EDS updates for this Cluster.

service_name

(string) Optional alternative to cluster name to present to EDS. This does not have the same restrictions as cluster name, i.e. it may be arbitrary length.

Cluster.LbSubsetConfig

[Cluster.LbSubsetConfig proto]

Optionally divide the endpoints in this cluster into subsets defined by endpoint metadata and selected by route and weighted cluster metadata.

  1. {
  2.   "fallback_policy": "...",
  3.   "default_subset": "{...}",
  4.   "subset_selectors": []
  5. }

fallback_policy

(Cluster.LbSubsetConfig.LbSubsetFallbackPolicy) The behavior used when no endpoint subset matches the selected route’s metadata. The value defaults to NO_FALLBACK.

default_subset

(Struct) Specifies the default subset of endpoints used during fallback if fallback_policy is DEFAULT_SUBSET. Each field in default_subset is compared to the matching LbEndpoint.Metadata under the envoy.lb namespace. It is valid for no hosts to match, in which case the behavior is the same as a fallback_policy of NO_FALLBACK.

subset_selectors

(Cluster.LbSubsetConfig.LbSubsetSelector) For each entry, LbEndpoint.Metadata’s envoy.lb namespace is traversed and a subset is created for each unique combination of key and value. For example:

  1. { "subset_selectors": [
  2.     { "keys": [ "version" ] },
  3.     { "keys": [ "stage", "hardware_type" ] }
  4. ]}

A subset is matched when the metadata from the selected route and weighted cluster contains the same keys and values as the subset’s metadata. The same host may appear in multiple subsets.

Cluster.LbSubsetConfig.LbSubsetSelector

[Cluster.LbSubsetConfig.LbSubsetSelector proto]

Specifications for subsets.

  1. {
  2.   "keys": []
  3. }

keys

(string) List of keys to match with the weighted cluster metadata.

Enum Cluster.LbSubsetConfig.LbSubsetFallbackPolicy

[Cluster.LbSubsetConfig.LbSubsetFallbackPolicy proto]

If NO_FALLBACK is selected, a result equivalent to no healthy hosts is reported. If ANY_ENDPOINT is selected, any cluster endpoint may be returned (subject to policy, health checks, etc). If DEFAULT_SUBSET is selected, load balancing is performed over the endpoints matching the values from the default_subset field.

NO_FALLBACK

(DEFAULT) ⁣

ANY_ENDPOINT

⁣

DEFAULT_SUBSET

⁣

Cluster.RingHashLbConfig

[Cluster.RingHashLbConfig proto]

Specific configuration for the RingHash load balancing policy.

  1. {
  2.   "minimum_ring_size": "{...}"
  3. }

minimum_ring_size

(UInt64Value) Minimum hash ring size, i.e. total virtual nodes. A larger size will provide better request distribution since each host in the cluster will have more virtual nodes. Defaults to 1024. In the case that total number of hosts is greater than the minimum, each host will be allocated a single virtual node.

Cluster.CommonLbConfig

[Cluster.CommonLbConfig proto]

Common configuration for all load balancer implementations.

  1. {
  2.   "healthy_panic_threshold": "{...}"
  3. }

healthy_panic_threshold

(type.Percent) Configures the healthy panic threshold. If not specified, the default is 50%.

Note

The specified percent will be truncated to the nearest 1%.

Enum Cluster.DiscoveryType

[Cluster.DiscoveryType proto]

Refer to service discovery type for an explanation on each type.

STATIC

(DEFAULT) ⁣Refer to the static discovery type for an explanation.

STRICT_DNS

⁣Refer to the strict DNS discovery type for an explanation.

LOGICAL_DNS

⁣Refer to the logical DNS discovery type for an explanation.

EDS

⁣Refer to the service discovery type for an explanation.

ORIGINAL_DST

⁣Refer to the original destination discovery type for an explanation.

Enum Cluster.LbPolicy

[Cluster.LbPolicy proto]

Refer to load balancer type architecture overview section for information on each type.

ROUND_ROBIN

(DEFAULT) ⁣Refer to the round robin load balancing policy for an explanation.

LEAST_REQUEST

⁣Refer to the least request load balancing policy for an explanation.

RING_HASH

⁣Refer to the ring hash load balancing policy for an explanation.

RANDOM

⁣Refer to the random load balancing policy for an explanation.

ORIGINAL_DST_LB

⁣Refer to the original destination load balancing policy for an explanation.

MAGLEV

⁣Refer to the Maglev load balancing policy for an explanation.

Enum Cluster.DnsLookupFamily

[Cluster.DnsLookupFamily proto]

When V4_ONLY is selected, the DNS resolver will only perform a lookup for addresses in the IPv4 family. If V6_ONLY is selected, the DNS resolver will only perform a lookup for addresses in the IPv6 family. If AUTO is specified, the DNS resolver will first perform a lookup for addresses in the IPv6 family and fallback to a lookup for addresses in the IPv4 family. For cluster types other than STRICT_DNS and LOGICAL_DNS, this setting is ignored.

AUTO

(DEFAULT) ⁣

V4_ONLY

⁣

V6_ONLY

⁣

Enum Cluster.ClusterProtocolSelection

[Cluster.ClusterProtocolSelection proto]

USE_CONFIGURED_PROTOCOL

(DEFAULT) ⁣Cluster can only operate on one of the possible upstream protocols (HTTP1.1, HTTP2). If http2_protocol_options are present, HTTP2 will be used, otherwise HTTP1.1 will be used.

USE_DOWNSTREAM_PROTOCOL

⁣Use HTTP1.1 or HTTP2, depending on which one is used on the downstream connection.

UpstreamBindConfig

[UpstreamBindConfig proto]

An extensible structure containing the address Envoy should bind to when establishing upstream connections.

  1. {
  2.   "source_address": "{...}"
  3. }

source_address

(core.Address) The address Envoy should bind to when establishing upstream connections.