Cluster API

备注:内容来自 https://www.envoyproxy.io/docs/envoy/latest/api-v2/api/v2/cds.proto

Cluster配置

配置详细信息实际的源头是来自xDS API 中 Cluster 的 proto 定义文件,地址如下:

https://github.com/envoyproxy/envoy/blob/master/api/envoy/api/v2/cds.proto#L50

Cluster配置的JSON格式如下所示:

{
  "name": "...",
  "alt_stat_name": "...",
  "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": "{...}",
  "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) 提供群集的名称,该群集的名称在所有群集中必须是唯一的。 如果未提供 alt_stat_name,则在发出统计信息时使用群集名称。 任何:在发出统计信息时,群集名称中的:将转换为_。 默认情况下,群集名称的最大长度限制为60个字符。 通过将 --max-obj-name-len 命令行参数设置为所需的值,可以增加此限制。
alt_stat_name string 发出统计数据时要使用的群集名称的可选替代项。 任何:在发布统计信息时,名称中的:将转换为_。。 这不应与路由器过滤器头混淆。
type Cluster.DiscoveryType 用于解析集群的服务发现类型。
eds_cluster_config Cluster.EdsClusterConfig 用于群集EDS更新的配置。
connect_timeout Duration 新建到群集中主机的网络连接的超时。
per_connection_buffer_limit_bytes UInt32Value 集群连接读写缓冲区大小的软件限制。 如果未指定,则使用实现定义的默认值(1MiB)。
lb_policy Cluster.LbPolicy 负载均衡器类型,用于在群集中选择主机。
hosts core.Address 如果服务发现类型是STATIC,STRICT_DNS或LOGICAL_DNS,则需要设置主机。

这个字段已经被废弃,请设置 load_assignment 字段
load_assignment ClusterLoadAssignment 设置此选项是指定STATIC,STRICT_DNS或LOGICAL_DNS集群的成员所必需的。 此字段取代hosts字段。
health_checks core.HealthCheck 群集的可选活动运行状况检查配置。 如果未指定任何配置,则不会进行运行状况检查,并且所有集群成员始终被视为运行状况良好。
max_requests_per_connection UInt32Value 对单个上游连接的最大请求,可选。 HTTP/1.1和HTTP/2连接池实现都遵循此参数。如果没有指定,则没有限制。将此参数设置为1将有效禁用keep alive。
circuit_breakers cluster.CircuitBreakers 集群的熔断,可选。
tls_context auth.UpstreamTlsContext 用于连接到上游群集的TLS配置。 如果未指定TLS配置,则新连接不会用TLS。
common_http_protocol_options core.HttpProtocolOptions 处理HTTP请求时的其他选项。 这些选项适用于HTTP1和HTTP2请求。
http_protocol_options core.Http1ProtocolOptions 处理HTTP1请求时的其他选项。
http2_protocol_options core.Http2ProtocolOptions 即使需要默认的HTTP2协议选项,也必须设置此字段,以便Envoy在进行新的HTTP连接池连接时假定上游支持HTTP/2。 目前,Envoy仅支持上游连接的先验知识。 即使TLS与ALPN一起使用,也必须指定http2_protocol_options。 除此之外,这允许HTTP/2连接发生在纯文本上。
extension_protocol_options map extension_protocol_options字段用于为上游连接提供特定于扩展的协议选项。 密钥应与扩展过滤器名称匹配,例如“envoy.filters.network.thrift_proxy”。 有关特定选项的详细信息,请参阅扩展的文档。
dns_refresh_rate Duration 如果指定了DNS刷新率且群集类型为STRICT_DNS或LOGICAL_DNS,则此值将用作群集的DNS刷新率。 如果未指定此设置,则默认值为5000毫秒。 对于除STRICT_DNS和LOGICAL_DNS之外的集群类型,将忽略此设置。
dns_lookup_family Cluster.DnsLookupFamily DNS IP地址解析策略。 如果未指定此设置,则默认值为AUTO。
dns_resolvers core.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 core.BindConfig 用于绑定新建立的上游连接的可选配置。这将覆盖bootstrap proto中指定的任何bind_config。如果地址和端口为空,则不执行绑定。
lb_subset_config Cluster.LbSubsetConfig 负载均衡子集的配置。
ring_hash_lb_config Cluster.RingHashLbConfig Ring Hash负载均衡策略的可选配置。

LbPolicy选择的负载平衡算法的可选配置。 目前只有RING_HASH和LEAST_REQUEST具有其他配置选项。 指定ring_hash_lb_config或least_request_lb_config而不设置相应的LbPolicy将在运行时生成错误。

只能设置ring_hash_lb_config,original_dst_lb_config,least_request_lb_config中的一个。
original_dst_lb_config Cluster.OriginalDstLbConfig 原始目标负载平衡策略的可选配置。

LbPolicy选择的负载平衡算法的可选配置。 目前只有RING_HASH和LEAST_REQUEST具有其他配置选项。 指定ring_hash_lb_config或least_request_lb_config而不设置相应的LbPolicy将在运行时生成错误。

只能设置ring_hash_lb_config,original_dst_lb_config,least_request_lb_config中的一个。
least_request_lb_config Cluster.LeastRequestLbConfig LeastRequest负载平衡策略的可选配置。

LbPolicy选择的负载平衡算法的可选配置。 目前只有RING_HASH和LEAST_REQUEST具有其他配置选项。 指定ring_hash_lb_config或least_request_lb_config而不设置相应的LbPolicy将在运行时生成错误。

只能设置ring_hash_lb_config,original_dst_lb_config,least_request_lb_config中的一个。
common_lb_config Cluster.CommonLbConfig 所有负载均衡器实现的通用配置。
transport_socket core.TransportSocket 用于上游连接的自定义传输套接字实现,可选。
metadata core.Metadata 元数据字段可用于提供有关群集的其他信息。 它可用于统计信息,日志记录和不同的过滤器行为。 字段应使用反向DNS表示法来表示Envoy中哪个实体需要该信息。 例如,如果元数据用于路由器过滤器,则应将过滤器名称指定为envoy.router。
protocol_selection Cluster.ClusterProtocolSelection 确定Envoy如何选择用于与上游主机通信的协议。
upstream_connection_options UpstreamConnectionOptions 上游连接的可选选项。
close_connections_on_host_health_failure bool 如果上游主机变得不健康(由配置的运行状况检查或异常检测确定),立即关闭与故障主机的所有连接。

目前仅支持tcp_proxy创建的连接。

当检测到不健康状态时,此功能的当前实现会立即关闭所有连接。 如果向上游主机开放的大量连接变得不健康,Envoy可能会花费大量时间专门关闭这些连接,而不会处理任何其他流量。
drain_connections_on_host_removal bool 如果此群集使用EDS或STRICT_DNS配置其主机,请立即从已从服务发现中删除的任何主机中排除连接。

这仅影响正在进行健康检查的主机的行为。 如果此标志未设置为true,Envoy将等待,直到主机无法进行活动运行状况检查,然后才能将其从群集中删除。