1 - XDS API中的CDS概述
介绍Envoy的XDS API中的CDS
CDS API定义在 api/envoy/api/v2/cds.proto
:
service ClusterDiscoveryService {
rpc StreamClusters(stream DiscoveryRequest) returns (stream DiscoveryResponse) {
}
rpc DeltaClusters(stream DeltaDiscoveryRequest) returns (stream DeltaDiscoveryResponse) {
}
rpc FetchClusters(DiscoveryRequest) returns (DiscoveryResponse) {
}
}
2 - Cluster API
Envoy的Cluster配置参考手册
备注:内容来自 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 | 负载均衡器类型,用于在群集中选择主机。 |
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<string, Struct> | 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将等待,直到主机无法进行活动运行状况检查,然后才能将其从群集中删除。 |