Clusters¶

Cluster¶

Configuration for a single upstream cluster.

{
  "name": "...",
  "alt_stat_name": "...",
  "type": "...",
  "cluster_type": "{...}",
  "eds_cluster_config": "{...}",
  "connect_timeout": "{...}",
  "per_connection_buffer_limit_bytes": "{...}",
  "lb_policy": "...",
  "hosts": [],
  "load_assignment": "{...}",
  "health_checks": [],
  "max_requests_per_connection": "{...}",
  "circuit_breakers": "{...}",
  "tls_context": "{...}",
  "common_http_protocol_options": "{...}",
  "http_protocol_options": "{...}",
  "http2_protocol_options": "{...}",
  "extension_protocol_options": "{...}",
  "typed_extension_protocol_options": "{...}",
  "dns_refresh_rate": "{...}",
  "dns_lookup_family": "...",
  "dns_resolvers": [],
  "outlier_detection": "{...}",
  "cleanup_interval": "{...}",
  "upstream_bind_config": "{...}",
  "lb_subset_config": "{...}",
  "ring_hash_lb_config": "{...}",
  "original_dst_lb_config": "{...}",
  "least_request_lb_config": "{...}",
  "common_lb_config": "{...}",
  "transport_socket": "{...}",
  "metadata": "{...}",
  "protocol_selection": "...",
  "upstream_connection_options": "{...}",
  "close_connections_on_host_health_failure": "...",
  "drain_connections_on_host_removal": "..."
}

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.

Only one of type, cluster_type may be set.

cluster_type

(Cluster.CustomClusterType) The custom cluster type.

Only one of type, cluster_type may be set.

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.

Attention

This field is deprecated. Set the load_assignment field instead.

load_assignment: (ClusterLoadAssignment) Setting this is required for specifying members of STATIC, STRICT_DNS or LOGICAL_DNS clusters. This field supersedes hosts field.

Attention

Setting this allows non-EDS cluster types to contain embedded EDS equivalent endpoint assignments. Setting this overrides hosts values.

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.

extension_protocol_options: (map<string, Struct>) The extension_protocol_options field is used to provide extension-specific protocol options for upstream connections. The key should match the extension filter name, such as “envoy.filters.network.thrift_proxy”. See the extension’s documentation for details on specific options.

typed_extension_protocol_options: (map<string, Any>) The extension_protocol_options field is used to provide extension-specific protocol options for upstream connections. The key should match the extension filter name, such as “envoy.filters.network.thrift_proxy”. See the extension’s documentation for details on specific options.

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 5000ms. 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.

Optional configuration for the load balancing algorithm selected by LbPolicy. Currently only RING_HASH and LEAST_REQUEST has additional configuration options. Specifying ring_hash_lb_config or least_request_lb_config without setting the corresponding LbPolicy will generate an error at runtime.

Only one of ring_hash_lb_config, original_dst_lb_config, least_request_lb_config may be set.

original_dst_lb_config

(Cluster.OriginalDstLbConfig) Optional configuration for the Original Destination load balancing policy.

Optional configuration for the load balancing algorithm selected by LbPolicy. Currently only RING_HASH and LEAST_REQUEST has additional configuration options. Specifying ring_hash_lb_config or least_request_lb_config without setting the corresponding LbPolicy will generate an error at runtime.

Only one of ring_hash_lb_config, original_dst_lb_config, least_request_lb_config may be set.

least_request_lb_config

(Cluster.LeastRequestLbConfig) Optional configuration for the LeastRequest load balancing policy.

Optional configuration for the load balancing algorithm selected by LbPolicy. Currently only RING_HASH and LEAST_REQUEST has additional configuration options. Specifying ring_hash_lb_config or least_request_lb_config without setting the corresponding LbPolicy will generate an error at runtime.

Only one of ring_hash_lb_config, original_dst_lb_config, least_request_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.

upstream_connection_options: (UpstreamConnectionOptions) Optional options for upstream connections.

close_connections_on_host_health_failure: (bool) If an upstream host becomes unhealthy (as determined by the configured health checks or outlier detection), immediately close all connections to the failed host.

Note

This is currently only supported for connections created by tcp_proxy.

Note

The current implementation of this feature closes all connections immediately when the unhealthy status is detected. If there are a large number of connections open to an upstream host that becomes unhealthy, Envoy may spend a substantial amount of time exclusively closing these connections, and not processing any other traffic.

drain_connections_on_host_removal

(bool) If this cluster uses EDS or STRICT_DNS to configure its hosts, immediately drain connections from any hosts that are removed from service discovery.

This only affects behavior for hosts that are being actively health checked. If this flag is not set to true, Envoy will wait until the hosts fail active health checking before removing it from the cluster.

Cluster.CustomClusterType¶

[Cluster.CustomClusterType proto]

Extended cluster type.

{
  "name": "...",
  "typed_config": "{...}"
}

name: (string, REQUIRED) The type of the cluster to instantiate. The name must match a supported cluster type.

typed_config: (Any) Cluster specific configuration which depends on the cluster being instantiated. See the supported cluster for further documentation.

Cluster.EdsClusterConfig¶

[Cluster.EdsClusterConfig proto]

Only valid when discovery type is EDS.

{
  "eds_config": "{...}",
  "service_name": "..."
}

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.

{
  "fallback_policy": "...",
  "default_subset": "{...}",
  "subset_selectors": [],
  "locality_weight_aware": "...",
  "scale_locality_weight": "...",
  "panic_mode_any": "..."
}

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:

{ "subset_selectors": [
    { "keys": [ "version" ] },
    { "keys": [ "stage", "hardware_type" ] }
]}

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

locality_weight_aware

(bool) If true, routing to subsets will take into account the localities and locality weights of the endpoints when making the routing decision.

There are some potential pitfalls associated with enabling this feature, as the resulting traffic split after applying both a subset match and locality weights might be undesirable.

Consider for example a situation in which you have 50/50 split across two localities X/Y which have 100 hosts each without subsetting. If the subset LB results in X having only 1 host selected but Y having 100, then a lot more load is being dumped on the single host in X than originally anticipated in the load balancing assignment delivered via EDS.

scale_locality_weight: (bool) When used with locality_weight_aware, scales the weight of each locality by the ratio of hosts in the subset vs hosts in the original subset. This aims to even out the load going to an individual locality if said locality is disproportionally affected by the subset predicate.

panic_mode_any

(bool) If true, when a fallback policy is configured and its corresponding subset fails to find a host this will cause any host to be selected instead.

This is useful when using the default subset as the fallback policy, given the default subset might become empty. With this option enabled, if that happens the LB will attempt to select a host from the entire cluster.

Cluster.LbSubsetConfig.LbSubsetSelector¶

[Cluster.LbSubsetConfig.LbSubsetSelector proto]

Specifications for subsets.

{
  "keys": []
}

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.LeastRequestLbConfig¶

[Cluster.LeastRequestLbConfig proto]

Specific configuration for the LeastRequest load balancing policy.

{
  "choice_count": "{...}"
}

choice_count: (UInt32Value) The number of random healthy hosts from which the host with the fewest active requests will be chosen. Defaults to 2 so that we perform two-choice selection if the field is not set.

Cluster.RingHashLbConfig¶

[Cluster.RingHashLbConfig proto]

Specific configuration for the RingHash load balancing policy.

{
  "minimum_ring_size": "{...}",
  "hash_function": "...",
  "maximum_ring_size": "{...}"
}

minimum_ring_size: (UInt64Value) Minimum hash ring size. The larger the ring is (that is, the more hashes there are for each provided host) the better the request distribution will reflect the desired weights. Defaults to 1024 entries, and limited to 8M entries. See also maximum_ring_size.

hash_function: (Cluster.RingHashLbConfig.HashFunction) The hash function used to hash hosts onto the ketama ring. The value defaults to XX_HASH.

maximum_ring_size: (UInt64Value) Maximum hash ring size. Defaults to 8M entries, and limited to 8M entries, but can be lowered to further constrain resource use. See also minimum_ring_size.

Enum Cluster.RingHashLbConfig.HashFunction¶

[Cluster.RingHashLbConfig.HashFunction proto]

The hash function used to hash hosts onto the ketama ring.

XX_HASH: (DEFAULT) ⁣Use xxHash, this is the default hash function.

MURMUR_HASH_2: ⁣Use MurmurHash2, this is compatible with std:hash<string> in GNU libstdc++ 3.4.20 or above. This is typically the case when compiled on Linux and not macOS.

Cluster.OriginalDstLbConfig¶

[Cluster.OriginalDstLbConfig proto]

Specific configuration for the Original Destination load balancing policy.

{
  "use_http_header": "..."
}

use_http_header: (bool) When true, x-envoy-original-dst-host can be used to override destination address.

Attention

This header isn’t sanitized by default, so enabling this feature allows HTTP clients to route traffic to arbitrary hosts and/or ports, which may have serious security consequences.

Cluster.CommonLbConfig¶

[Cluster.CommonLbConfig proto]

Common configuration for all load balancer implementations.

{
  "healthy_panic_threshold": "{...}",
  "zone_aware_lb_config": "{...}",
  "locality_weighted_lb_config": "{...}",
  "update_merge_window": "{...}"
}

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%.

zone_aware_lb_config

(Cluster.CommonLbConfig.ZoneAwareLbConfig)

Only one of zone_aware_lb_config, locality_weighted_lb_config may be set.

locality_weighted_lb_config

(Cluster.CommonLbConfig.LocalityWeightedLbConfig)

Only one of zone_aware_lb_config, locality_weighted_lb_config may be set.

update_merge_window

(Duration) If set, all health check/weight/metadata updates that happen within this duration will be merged and delivered in one shot when the duration expires. The start of the duration is when the first update happens. This is useful for big clusters, with potentially noisy deploys that might trigger excessive CPU usage due to a constant stream of healthcheck state changes or metadata updates. The first set of updates to be seen apply immediately (e.g.: a new cluster).

If this is not set, we default to a merge window of 1000ms. To disable it, set the merge window to 0.

Note: merging does not apply to cluster membership changes (e.g.: adds/removes); this is because merging those updates isn’t currently safe. See https://github.com/envoyproxy/envoy/pull/3941.

Cluster.CommonLbConfig.ZoneAwareLbConfig¶

[Cluster.CommonLbConfig.ZoneAwareLbConfig proto]

Configuration for zone aware routing.

{
  "routing_enabled": "{...}",
  "min_cluster_size": "{...}"
}

routing_enabled: (type.Percent) Configures percentage of requests that will be considered for zone aware routing if zone aware routing is configured. If not specified, the default is 100%. * runtime values. * Zone aware routing support.

min_cluster_size: (UInt64Value) Configures minimum upstream cluster size required for zone aware routing If upstream cluster size is less than specified, zone aware routing is not performed even if zone aware routing is configured. If not specified, the default is 6. * runtime values. * Zone aware routing support.

Cluster.CommonLbConfig.LocalityWeightedLbConfig¶

[Cluster.CommonLbConfig.LocalityWeightedLbConfig proto]

Configuration for locality weighted load balancing

{}

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.

{
  "source_address": "{...}"
}

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

UpstreamConnectionOptions¶

[UpstreamConnectionOptions proto]

{
  "tcp_keepalive": "{...}"
}

tcp_keepalive: (core.TcpKeepalive) If set then set SO_KEEPALIVE on the socket to enable TCP Keepalives.