集群配置 (proto)

config.cluster.v3.Cluster

单个上游集群的配置。

{
  "transport_socket_matches": [],
  "name": ...,
  "alt_stat_name": ...,
  "type": ...,
  "cluster_type": {...},
  "eds_cluster_config": {...},
  "connect_timeout": {...},
  "per_connection_buffer_limit_bytes": {...},
  "lb_policy": ...,
  "load_assignment": {...},
  "health_checks": [],
  "max_requests_per_connection": {...},
  "circuit_breakers": {...},
  "upstream_http_protocol_options": {...},
  "common_http_protocol_options": {...},
  "http_protocol_options": {...},
  "http2_protocol_options": {...},
  "typed_extension_protocol_options": {...},
  "dns_refresh_rate": {...},
  "dns_jitter": {...},
  "dns_failure_refresh_rate": {...},
  "respect_dns_ttl": ...,
  "dns_lookup_family": ...,
  "dns_resolvers": [],
  "use_tcp_for_dns_lookups": ...,
  "dns_resolution_config": {...},
  "typed_dns_resolver_config": {...},
  "wait_for_warm_on_init": {...},
  "outlier_detection": {...},
  "cleanup_interval": {...},
  "upstream_bind_config": {...},
  "lb_subset_config": {...},
  "ring_hash_lb_config": {...},
  "maglev_lb_config": {...},
  "original_dst_lb_config": {...},
  "least_request_lb_config": {...},
  "round_robin_lb_config": {...},
  "common_lb_config": {...},
  "transport_socket": {...},
  "metadata": {...},
  "protocol_selection": ...,
  "upstream_connection_options": {...},
  "close_connections_on_host_health_failure": ...,
  "ignore_health_on_host_removal": ...,
  "filters": [],
  "load_balancing_policy": {...},
  "lrs_report_endpoint_metrics": [],
  "track_timeout_budgets": ...,
  "upstream_config": {...},
  "track_cluster_stats": {...},
  "preconnect_policy": {...},
  "connection_pool_per_downstream_connection": ...
}

transport_socket_matches

(repeated config.cluster.v3.Cluster.TransportSocketMatch) 用于为不同端点使用不同传输套接字的配置。在 LbEndpoint.Metadata 中 envoy.transport_socket_match 的条目用于与传输套接字匹配，因为它们出现在列表中。如果未找到匹配项，则在 LocalityLbEndpoints.Metadata 中继续搜索。使用第一个 match。例如，使用以下匹配项

transport_socket_matches:
- name: "enableMTLS"
  match:
    acceptMTLS: true
  transport_socket:
    name: envoy.transport_sockets.tls
    config: { ... } # tls socket configuration
- name: "defaultToPlaintext"
  match: {}
  transport_socket:
    name: envoy.transport_sockets.raw_buffer

连接到端点，这些端点在 envoy.transport_socket_match 下的元数据值具有“acceptMTLS”/“true”键/值对，使用“enableMTLS”套接字配置。

如果提供了具有空匹配条件的 socket match，则该匹配项始终与任何端点匹配。例如，上面情况下的“defaultToPlaintext”套接字匹配项。

如果端点元数据在 envoy.transport_socket_match 下的值与任何 TransportSocketMatch 不匹配，则会检查区域元数据以查找匹配项。如果端点或区域元数据中没有任何匹配项，套接字配置将回退到使用此集群中指定的 tls_context 或 transport_socket。

此字段允许逐步灵活地更改传输套接字配置。

EDS 中端点的元数据可以指示传输套接字功能。例如，端点的元数据可以具有两个键值对，如“acceptMTLS”：“true”，“acceptPlaintext”：“true”。而其他一些端点，只接受明文流量，具有“acceptPlaintext”：“true”元数据信息。

然后，xDS 服务器可以将 CDS 配置到客户端 Envoy A，以便为具有“acceptMTLS”：“true”的端点发送双向 TLS 流量，方法是在此字段中添加相应的 TransportSocketMatch。其他客户端 Envoy 接收不设置 transport_socket_match 的 CDS，并继续向同一集群发送明文流量。

此字段可用于通过在健康检查的 transport socket match criteria 字段中添加匹配的键/值对来指定健康检查的自定义传输套接字配置。

name: (string, REQUIRED) 提供集群的名称，该名称在所有集群中必须是唯一的。如果未提供 alt_stat_name，则在发出统计信息时将使用集群名称。集群名称中的任何 : 在发出统计信息时将转换为 _。

alt_stat_name: (string) 用于可观察性的集群名称的可选替代项。此名称用于发出集群的统计信息和访问日志记录集群名称。这将显示为集群当前状态的配置转储中的附加信息，作为 observability_name，并在跟踪时作为附加标签“upstream_cluster.name”。注意：名称中的任何 : 在发出统计信息时将转换为 _。不要将其与 Router Filter Header 混淆。

type

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

只能设置 type、cluster_type 中的一个。

cluster_type

(config.cluster.v3.Cluster.CustomClusterType) 自定义集群类型。

只能设置 type、cluster_type 中的一个。

eds_cluster_config: (config.cluster.v3.Cluster.EdsClusterConfig) 用于集群的 EDS 更新的配置。

connect_timeout: (Duration) 建立与集群中主机的新网络连接的超时时间。如果未设置，将使用默认值 5 秒。

per_connection_buffer_limit_bytes

(UInt32Value) 集群连接读写缓冲区大小的软限制。如果未指定，将应用实现定义的默认值 (1MiB)。

注意

此字段应在存在不可信上游的情况下配置。

不可信环境的示例配置

per_connection_buffer_limit_bytes: 32768.0

lb_policy: (config.cluster.v3.Cluster.LbPolicy) 从集群中选择主机时使用的负载均衡器类型。

load_assignment: (config.endpoint.v3.ClusterLoadAssignment) 为指定 STATIC、STRICT_DNS 或 LOGICAL_DNS 集群的成员设置此项是必需的。此字段取代了 v2 API 中的 hosts 字段。

注意

设置此项允许非 EDS 集群类型包含嵌入的 EDS 等效端点分配。

health_checks: (repeated config.core.v3.HealthCheck) 集群的可选主动健康检查配置。如果未指定配置，则不会执行健康检查，并且所有集群成员始终被视为健康。

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

注意

此字段已弃用，取而代之的是 max_requests_per_connection 字段。

circuit_breakers: (config.cluster.v3.CircuitBreakers) 集群的可选断路。

upstream_http_protocol_options: (config.core.v3.UpstreamHttpProtocolOptions) 仅应用于上游 HTTP 连接的 HTTP 协议选项。这些选项适用于所有 HTTP 版本。此选项已弃用，取而代之的是 upstream_http_protocol_options，它位于 http_protocol_options 消息中。upstream_http_protocol_options 可以通过集群的 extension_protocol_options 设置。有关示例用法，请参阅 upstream_http_protocol_options。

common_http_protocol_options: (config.core.v3.HttpProtocolOptions) 在上游处理 HTTP 请求时的其他选项。这些选项将适用于 HTTP1 和 HTTP2 请求。此选项已弃用，取而代之的是 common_http_protocol_options，它位于 http_protocol_options 消息中。common_http_protocol_options 可以通过集群的 extension_protocol_options 设置。有关示例用法，请参阅 upstream_http_protocol_options。

http_protocol_options: (config.core.v3.Http1ProtocolOptions) 处理 HTTP1 请求时的其他选项。此选项已弃用，取而代之的是 http_protocol_options 消息中的 http_protocol_options 字段。http_protocol_options 可以通过集群的 extension_protocol_options 设置。有关示例用法，请参阅 upstream_http_protocol_options。

http2_protocol_options

(config.core.v3.Http2ProtocolOptions) 即使需要默认的 HTTP/2 协议选项，也必须设置此字段，以便 Envoy 在建立新的 HTTP 连接池连接时假定上游支持 HTTP/2。目前，Envoy 仅支持上游连接的先验知识。即使使用 ALPN 的 TLS，也必须指定 http2_protocol_options。顺便说一下，这允许在纯文本上进行 HTTP/2 连接。此功能已弃用，取而代之的是 http_protocol_options 消息中的 http2_protocol_options 字段。 http2_protocol_options 可以通过集群的 extension_protocol_options 设置。请参阅 upstream_http_protocol_options 以了解示例用法。

注意

此字段应在存在不可信上游的情况下配置。

不可信环境的示例配置

http2_protocol_options:
  initial_connection_window_size: 1048576.0
  initial_stream_window_size: 65536.0

typed_extension_protocol_options: (repeated map<string, Any>) extension_protocol_options 字段用于为上游连接提供特定于扩展的协议选项。键应与扩展过滤器名称匹配，例如“envoy.filters.network.thrift_proxy”。请参阅扩展的文档以了解有关特定选项的详细信息。

dns_refresh_rate: (Duration) 如果指定了 DNS 刷新速率，并且集群类型为 STRICT_DNS 或 LOGICAL_DNS，则此值用作集群的 DNS 刷新速率。配置的值必须至少为 1 毫秒。如果未指定此设置，则默认值为 5000 毫秒。对于除 STRICT_DNS 和 LOGICAL_DNS 以外的集群类型，此设置将被忽略。

dns_jitter: (Duration) 如果集群类型为 STRICT_DNS 或 LOGICAL_DNS，则可以选择指定 DNS 抖动。 DNS 抖动会导致集群通过随机时间延迟刷新 DNS 条目，以避免 DNS 请求的集中涌入。此值设置随机量上限（不含）。如果省略此值，则不会进行抖动。对于除 STRICT_DNS 和 LOGICAL_DNS 以外的集群类型，此设置将被忽略。

dns_failure_refresh_rate: (config.cluster.v3.Cluster.RefreshRate) 如果指定了 DNS 故障刷新速率，并且集群类型为 STRICT_DNS 或 LOGICAL_DNS，则在请求失败时用作集群的 DNS 刷新速率。如果未指定此设置，则故障刷新速率默认为 DNS 刷新速率。对于除 STRICT_DNS 和 LOGICAL_DNS 以外的集群类型，此设置将被忽略。

respect_dns_ttl: (bool) 用于设置集群 DNS 刷新速率的可选配置。如果将该值设置为 true，则集群的 DNS 刷新速率将设置为来自 DNS 解析的资源记录的 TTL。

dns_lookup_family: (config.cluster.v3.Cluster.DnsLookupFamily) DNS IP 地址解析策略。如果未指定此设置，则默认值为 AUTO。

dns_resolvers: (repeated config.core.v3.Address) 如果指定了 DNS 解析器，并且集群类型为 STRICT_DNS 或 LOGICAL_DNS，则此值用于指定集群的 DNS 解析器。如果未指定此设置，则默认值为默认解析器，该解析器使用 /etc/resolv.conf 进行配置。对于除 STRICT_DNS 和 LOGICAL_DNS 以外的集群类型，此设置将被忽略。此字段已弃用，取而代之的是 dns_resolution_config，它将所有 DNS 解析器配置汇总到单个消息中。

use_tcp_for_dns_lookups: (bool) 始终使用 TCP 查询而不是 UDP 查询进行 DNS 查找。此字段已弃用，取而代之的是 dns_resolution_config，它将所有 DNS 解析器配置汇总到单个消息中。

dns_resolution_config: (config.core.v3.DnsResolutionConfig) DNS 解析配置，包括底层 DNS 解析器地址和选项。此字段已弃用，取而代之的是 typed_dns_resolver_config。

typed_dns_resolver_config

(config.core.v3.TypedExtensionConfig) DNS 解析器类型配置扩展。此扩展可用于配置 c-ares、apple 或任何其他 DNS 解析器类型以及相关参数。例如，CaresDnsResolverConfig 的对象可以打包到此 typed_dns_resolver_config 中。此配置替换了 dns_resolution_config 配置。在同时存在 dns_resolution_config 和 typed_dns_resolver_config 的过渡期间，当 typed_dns_resolver_config 存在时，Envoy 将使用它并忽略 dns_resolution_config。当 typed_dns_resolver_config 缺失时，将使用默认行为。

提示

此扩展类别具有以下已知扩展

wait_for_warm_on_init: (BoolValue) 用于让集群准备就绪状态阻塞在预热上的可选配置。目前，仅适用于 STRICT_DNS 或 LOGICAL_DNS 或 Redis 集群。如果为 true，则集群准备就绪状态将阻塞在预热上。如果为 false，则无论预热是否已完成，集群都将完成初始化。默认值为 true。

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

cleanup_interval: (Duration) 用于从集群类型 ORIGINAL_DST 中删除陈旧主机的间隔。如果在该间隔内未用作上游目标，则主机将被视为陈旧。随着新连接被重定向到 Envoy，新主机将按需添加到原始目标集群，从而导致集群中的主机数量随着时间的推移而增长。未被视为陈旧（它们被用作活动目标）的主机将保留在集群中，这使得与它们的连接保持打开状态，从而节省了原本用于打开新连接的延迟。如果未指定此设置，则默认值为 5000 毫秒。对于除 ORIGINAL_DST 以外的集群类型，此设置将被忽略。

upstream_bind_config: (config.core.v3.BindConfig) 用于绑定新建立的上游连接的可选配置。此配置会覆盖引导程序协议中指定的任何 bind_config。如果地址和端口为空，则不会执行绑定。

lb_subset_config: (config.cluster.v3.Cluster.LbSubsetConfig) 用于负载均衡子集的配置。

ring_hash_lb_config

(config.cluster.v3.Cluster.RingHashLbConfig) 环形哈希负载均衡策略的可选配置。