V2 API参考 - 集群&集群发现 - 《EnvoyProxy 智能代理中文参考文档 v1.5.0》

集群&集群发现
返回

集群&集群发现

Cluster
Cluster.EdsClusterConfig
Cluster.OutlierDetection
Cluster.LbSubsetConfig
Cluster.LbSubsetConfig.LbSubsetSelector
Cluster.LbSubsetConfig.LbSubsetFallbackPolicy (Enum)
Cluster.RingHashLbConfig
Cluster.RingHashLbConfig.DeprecatedV
Cluster.DiscoveryType (Enum)
Cluster.LbPolicy (Enum)
Cluster.DnsLookupFamily (Enum)
UpstreamBindConfig
CircuitBreakers
CircuitBreakers.Thresholds

Cluster

{
  "name": "...",
  "type": "...",
  "eds_cluster_config": "{...}",
  "connect_timeout": "{...}",
  "per_connection_buffer_limit_bytes": "{...}",
  "lb_policy": "...",
  "hosts": [],
  "health_checks": [],
  "max_requests_per_connection": "{...}",
  "circuit_breakers": "{...}",
  "tls_context": "{...}",
  "http_protocol_options": "{...}",
  "http2_protocol_options": "{...}",
  "dns_refresh_rate": "{...}",
  "dns_lookup_family": "...",
  "dns_resolvers": [],
  "outlier_detection": "{...}",
  "cleanup_interval": "{...}",
  "upstream_bind_config": "{...}",
  "lb_subset_config": "{...}",
  "ring_hash_lb_config": "{...}",
  "transport_socket": "{...}"
}

name

(string, REQUIRED) 提供在所有群集中必须唯一的群集名称。在发布统计信息时，会使用集群名称。在发布任何统计信息时，集群名称将被转换为_。默认情况下，群集名称的最大长度限制为60个字符。可通过--max-obj-name-len命令行参数，提高此上限。
type

(Cluster.DiscoveryType)) 用于解析群集的服务发现类型。
eds_cluster_config

(Cluster.EdsClusterConfig) 用于群集的EDS更新配置。
connect_timeout

(Duration) 连接到该群集中主机的超时时长。
per_connection_buffer_limit_bytes

(UInt32Value) 连接集群的读写缓冲区大小。如果未指定，则使用默认值（1MB）。
lb_policy

(Cluster.LbPolicy)) 在集群中选择主机时使用的负载平衡器类型。
hosts

(Address) 如果服务发现类型是STATIC，STRICT_DNS或LOGICAL_DNS，则需要配置。
health_checks

(HealthCheck) 群集可选的健康检查配置。如果未指定配置，则不会执行健康检查，并且假定所有群集成员都将始终处于健康状态。
max_requests_per_connection

(UInt32Value) 可选，单个上游连接的最大请求数。HTTP/1.1和HTTP/2连接池都遵守此参数。如果没有指定，则没有限制。若此参数设置为1将有效地禁用保活状态的连接。
circuit_breakers

(CircuitBreakers) 可选，集群熔断配置。
tls_context

(UpstreamTlsContext) 连接到上游群集的TLS配置。如果没有指定TLS配置，则新连接不会使用TLS。
http_protocol_options

(Http1ProtocolOptions) 处理HTTP1请求时的其他选项。

只能设置http_protocol_options和http2_protocol_options其中一个配置。
http2_protocol_options

(Http2ProtocolOptions) 即使需要默认的HTTP2协议选项，也必须设置此字段，以便Envoy将在创建新的HTTP连接池时，假定上游支持HTTP/2。目前，Envoy仅支持上游连接的先验证。即使TLS与ALPN一起使用，也必须指定http2_protocol_options。另外，这允许HTTP/2通过纯文本连接。

只能设置http_protocol_options和http2_protocol_options其中一个配置。
dns_refresh_rate

(Duration) 指定DNS刷新率，在群集类型为STRICT_DNS或LOGICAL_DNS时，则将此值用作群集的DNS刷新率。如果未指定此设置，则此值默认为5000。对于STRICT_DNS和LOGICAL_DNS以外的群集类型，此设置将被忽略。
dns_lookup_family

(Cluster.DnsLookupFamily)) DNS IP地址解析策略。如果未指定此设置，则该值默认为V4_ONLY。
dns_resolvers

(Address) 如果指定了DNS解析程序，并且群集类型是STRICT_DNS或LOGICAL_DNS，则此值用于指定群集的dns解析程序。如果未指定此设置，则该值默认为使用/etc/resolv.conf配置的默认解析器。对于STRICT_DNS和LOGICAL_DNS以外的其他集群类型，此设置将被忽略。
outlier_detection

(Cluster.OutlierDetection) 如果指定，则会为此上游群集启用异常值检测。每个配置值都可以通过运行时配置覆盖。
cleanup_interval

(Duration) 从集群类型ORIGINAL_DST中删除过期主机的时间间隔。如果主机在这段时间内没有被用作上游目的地，则认为它们是陈旧的。随着新的连接重定向到Envoy，新的主机将按需添加到原始目标集群，从而导致集群中的主机数量随着时间而增长。没有陈旧的主机（它们被主动用作目的地）被保存在群集中，从而允许与它们的连接保持打开状态，从而节省了打开新连接所花费的等待时间。如果未指定此设置，则该值默认为5000毫秒。对于ORIGINAL_DST以外的其他群集类型，此设置将被忽略。
upstream_bind_config

(BindConfig) 用于绑定新建立的上游连接的可选配置。这将覆盖bootstrap proto中指定的任何bind_config。如果地址和端口是空的，则不执行绑定。
lb_subset_config

(Cluster.LbSubsetConfig) 配置负载平衡子集。
ring_hash_lb_config

(Cluster.RingHashLbConfig) 可选，配置环哈希负载平衡策略。只能设置一个ring_hash_lb_config。
transport_socket

(TransportSocket) 请参阅 base.TransportSocket描述。

Cluster.EdsClusterConfig

Cluster.EdsClusterConfig proto

只有当集群发现类型是EDS时才有效。

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

eds_config

(ConfigSource) 此群集的EDS更新源的配置。
service_name

(string) 可选，替代集群的名称，提供给EDS服务。这与集群名称没有同样的限制，即它可以是任意的长度。

Cluster.OutlierDetection

Cluster.OutlierDetection proto

有关异常值检测的更多信息，请参阅架构概述。

{
  "consecutive_5xx": "{...}",
  "interval": "{...}",
  "base_ejection_time": "{...}",
  "max_ejection_percent": "{...}",
  "enforcing_consecutive_5xx": "{...}",
  "enforcing_success_rate": "{...}",
  "success_rate_minimum_hosts": "{...}",
  "success_rate_request_volume": "{...}",
  "success_rate_stdev_factor": "{...}",
  "consecutive_gateway_failure": "{...}",
  "enforcing_consecutive_gateway_failure": "{...}"
}

consecutive_5xx

(UInt32Value) 发生连续5xx逐出主机之前，连续5xx响应的数量。默认为5。
interval

(Duration) 每次异常值分析扫描的时间间隔，这可能导致新抛出异常以及主机被重新添加到服务集群。默认为10000ms或10s。
base_ejection_time

(Duration) 主机弹出的基准时间。实际时间等于基本时间乘以主机被逐出的次数。默认为30000ms或30s。
max_ejection_percent

(UInt32Value) 由于异常检测而逐出的主机占上游群集的最大百分比。默认为10％。
enforcing_consecutive_5xx

(UInt32Value) 当通过连续5xx检测到异常状态时，主机实际被逐出的几率百分比。这个设置可以用来禁止逐出或者缓慢地加速。默认为100。
enforcing_success_rate

(UInt32Value) 通过成功率统计检测到异常状态时，主机实际被逐出的几率百分比。这个设置可以用来禁止逐出或者缓慢地加速。默认为100。
success_rate_minimum_hosts

(UInt32Value) 必须具有足够的请求量来检测成功率异常值的群集中的主机数量。如果主机数量小于此设置，则不会为群集中的任何主机执行通过成功率统计信息的异常值检测。默认为5。
success_rate_request_volume

(UInt32Value) 在一个时间间隔内（如上述定义的时间间隔）必须收集的最小请求总数，以便将此主机包含在基于成功率的异常值检测中。如果低于此设置，则不会为该主机执行通过成功率统计的异常值检测。默认为100。
success_rate_stdev_factor

(UInt32Value) 这个因子被用来确定异常逐出成功率的阈值。逐出阈值是平均成功率与该因子与平均成功率的标准偏差的乘积之差：mean - （stdev * success_rate_stdev_factor）。这个因素除以一千得到一个两位小数值。也就是说，如果期望的因子是1.9，运行时间值应该是1900，默认为1900。
consecutive_gateway_failure

(UInt32Value) 逐出之前连续发生的连续网关故障数量，包括（502,503,504状态或连接错误，映射到其中一个状态代码）默认为5。
enforcing_consecutive_gateway_failure

(UInt32Value) 当通过连续的网关故障检测到异常状态时，主机实际被逐出的几率百分比。这个设置可以用来禁止逐出或者缓慢地加速。默认为0。

Cluster.LbSubsetConfig

Cluster.LbSubsetConfig proto

（可选）将此群集中的端口划分为由端口元数据定义的子集，并按路由和加权群集元数据进行选择。

{
  "fallback_policy": "...",
  "default_subset": "{...}",
  "subset_selectors": []
}

fallback_policy

(Cluster.LbSubsetConfig.LbSubsetFallbackPolicy) 选定路由的元数据没有响应的端口子集匹配时使用的行为。该值默认为NO_FALLBACK。
default_subset

(Struct) 如果fallback_policy为DEFAULT_SUBSET，则指定在回退期间使用的端点的默认子集。将default_subset中的每个字段与envoy.lb命名空间下的匹配LbEndpoint.Metadata进行比较。没有主机匹配是有效的，在这种情况下，行为与NO_FALLBACK的fallback_policy`相同。
subset_selectors

(Cluster.LbSubsetConfig.LbSubsetSelector) 对于每个条目，遍历LbEndpoint.Metadata的envoy.lb命名空间，并为每个唯一的key和value组合创建一个子集。例如：
```
{ "subset_selectors": [
  { "keys": [ "version" ] },
  { "keys": [ "stage", "hardware_type" ] }
]}
```
当来自所选路由和加权群集的元数据包含与子集的元数据相同的key和value时，匹配子集。相同的主机可能出现在多个子集中。

Cluster.LbSubsetConfig.LbSubsetSelector

Cluster.LbSubsetConfig.LbSubsetSelector proto

子集的规格

{
  "keys": []
}

keys

(string) 与加权的群集元数据匹配的key列表。

Cluster.LbSubsetConfig.LbSubsetFallbackPolicy (Enum)

Cluster.LbSubsetConfig.LbSubsetFallbackPolicy proto

如果选择NO_FALLBACK，则会报告等效于没有健康主机的结果。如果选择了ANY_ENDPOINT，则可能会返回任何群集端点（取决于策略，健康检查等）。如果选择DEFAULT_SUBSET，则在匹配来自default_subset字段的值的端口上执行负载平衡。

NO_FALLBACK

(DEFAULT)
ANY_ENDPOINT
DEFAULT_SUBSET

Cluster.RingHashLbConfig

Cluster.RingHashLbConfig proto

RingHash负载均衡策略的具体配置。

{
  "minimum_ring_size": "{...}",
  "deprecated_v1": "{...}"
}

minimum_ring_size

(UInt64Value) 最小哈希环大小，即总的虚拟节点。更大的尺寸将提供更好的请求分布，因为集群中的每个主机将具有更多的虚拟节点。默认为1024.在主机总数大于最小值的情况下，每个主机将被分配一个虚拟节点。
deprecated_v1

(Cluster.RingHashLbConfig.DeprecatedV1) 已弃用的v1配置。

Cluster.RingHashLbConfig.DeprecatedV1

Cluster.RingHashLbConfig.DeprecatedV1 proto

{
  "use_std_hash": "{...}"
}

use_std_hash

(BoolValue) 默认为true，这意味着std::hash用于将主机散列到ketama环上。std::hash可能因平台而异。为此，Envoy默认最终会使用xxHash。该字段用于迁移目的，最终将被弃用。现在将其设置为false以使用xxHash。

Cluster.DiscoveryType (Enum)

Cluster.DiscoveryType proto

有关每种类型的解释，请参阅服务发现类型。

STATIC

(DEFAULT) 静态发现类型
STRICT_DNS

严格的DNS发现类型
LOGICAL_DNS

逻辑DNS发现类型
EDS

服务发现类型
ORIGINAL_DST

原始目标发现类型

Cluster.LbPolicy (Enum)

Cluster.LbPolicy proto

有关每种类型的信息，请参阅负载平衡器体系架构概述部分。

ROUND_ROBIN

(DEFAULT) 轮循负载平衡策略
LEAST_REQUEST

最小请求负载平衡策略
RING_HASH

环形散列负载平衡策略
RANDOM

随机负载平衡策略
ORIGINAL_DST_LB

原始目标负载平衡策略

Cluster.DnsLookupFamily (Enum)

Cluster.DnsLookupFamily proto

当选择V4_ONLY时，DNS解析器将仅执行IPv4系列中的地址查找。如果选择V6_ONLY，则DNS解析程序将仅执行IPv6系列中的地址查找。如果指定了AUTO，则DNS解析器将首先执行IPv6系列中的地址查找，然后回退到IPv4系列中的地址查找。对于STRICT_DNS和LOGICAL_DNS以外的集群类型，此设置将被忽略。

AUTO

(DEFAULT)
V4_ONLY
V6_ONLY

UpstreamBindConfig

UpstreamBindConfig proto

包含Envoy的可扩展地址结构，在与上游建立连接时绑定。

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

source_address

(Address) 建立上游连接时，Envoy应该绑定的地址。

CircuitBreakers

CircuitBreakers proto

可以为每个定义的优先级单独指定断路设置。

{
  "thresholds": []
}

thresholds

(CircuitBreakers.Thresholds) 如果使用相同的RoutingPriority定义多个阈值，则使用列表中的第一个阈值。如果给定的RoutingPriority没有定义Thresholds，则使用默认值。

CircuitBreakers.Thresholds

CircuitBreakers.Thresholds proto

为RoutingPriority定义断路阈值设置。

{
  "priority": "...",
  "max_connections": "{...}",
  "max_pending_requests": "{...}",
  "max_requests": "{...}",
  "max_retries": "{...}"
}

priority

(RoutingPriority) 设置指定断路器的RoutingPriority。
max_connections

(UInt32Value) Envoy将对上游群集进行的最大连接数。如果未指定，则默认值为1024。
max_pending_requests

(UInt32Value) Envoy将允许上游集群的最大待处理请求数。如果未指定，则默认值为1024。
max_requests

(UInt32Value) Envoy将对上游群集执行的最大并行请求数。如果未指定，则默认值为1024。
max_retries

(UInt32Value) Envoy允许上游集群执行的最大并行重试次数。如果未指定，则默认值为3。