本文档基于 v1.28, 原文地址: https://www.envoyproxy.io/docs/envoy/v1.28.7/configuration/configuration

Envoy 官网配置指南的中文翻译(监听):统计数据、运行时、监听过滤器

概述

顶级 Envoy 配置包含一个 侦听器 列表。每个单独的侦听器配置都具有以下格式：

v3 API 参考

统计数据

监听器

每个监听器都有一个以 listener.<address>. 为根的统计树（如果 stat_prefix 非空，则为 listener.<stat_prefix>.），包含以下统计信息：

TLS 统计数据

以下 TLS 统计数据的根为 listener.<address>.ssl.：

TCP statistics

使用 TCP 统计传输套接字时可用的以下 TCP 统计信息以 listener.<address>.tcp_stats. 为根：

注意 这些指标由操作系统提供。由于可用的操作系统指标和测量方法存在差异，因此不同操作系统或同一操作系统的不同版本之间的值可能不一致。

UDP 统计信息

以下 UDP 统计信息适用于 UDP 侦听器，并且以 listener.<address>.udp. 为根：

每个监听处理程序统计信息

每个监听器都另外有一个统计信息树，其根为 listener.<address>.<handler>.，其中包含每个处理程序的统计信息。如 线程模型 文档中所述，Envoy 有一个线程模型，其中包括主线程以及由 --concurrency 选项控制的 多个工作线程。 根路径里的 <handler> 等于main_thread、 worker_0、worker_1 等。这些统计数据可用于查找已接受或活动连接上每个处理程序/工作程序的不平衡情况。

监听管理器

监听管理器有一个以 listener_manager 为根的统计信息树，包含以下统计信息。统计信息名称中的任何字符 : 都将被替换为 _。

运行时

支持以下运行时设置：

envoy.resource_limits.listener.<name of listener>.connection_limit

设置指定侦听器的活动连接数限制。

监听过滤器

Envoy 具有以下内置监听过滤器。

HTTP Inspector

HTTP Inspector 监听过滤器允许检测应用程序协议是否为 HTTP， 如果是 HTTP，它会进一步检测 HTTP 协议（​​HTTP/1.x 或 HTTP/2）。 可以通过 FilterChainMatch 的 application_protocols 选择 FilterChain 来使用 HTTP Inspector 监听过滤器。

• 此过滤器应配置为 URL 类型 type.googleapis.com/envoy.extensions.filters.listener.http_inspector.v3.HttpInspector。
• 监听器过滤器 v3 API 参考

过滤器配置示例如下：

1
2
3
4

listener_filters:
  - name: "envoy.filters.listener.http_inspector"
    typed_config:
      "@type": type.googleapis.com/envoy.extensions.filters.listener.http_inspector.v3.HttpInspector

此过滤器有一个以 http_inspector 为根的统计树，其统计数据如下：

Local rate limit

• 本地速率限制架构概述
• 此过滤器 URL 类型应配置为 type.googleapis.com/envoy.extensions.filters.listener.local_ratelimit.v3.LocalRateLimit。
• v3 API 参考

注意

令牌桶在所有工作进程之间共享，因此速率限制适用于每个 Envoy 进程。

注意

还通过全局速率限制网络过滤器支持网络层的全局速率限制。

概述

本地速率限制过滤器将令牌桶速率限制应用于由过滤器的过滤器链处理的传入套接字。过滤器处理的每个套接字都使用一个令牌，如果没有可用的令牌，则套接字将立即关闭，而无需进一步的过滤器迭代。

注意

在当前实现中，每个过滤器和过滤器链都有独立的速率限制。

统计数据

每个配置的本地速率限制过滤器都有以 listener_local_ratelimit.<stat_prefix>. 为根的统计信息，其中包含以下统计信息：

运行时

本地速率限制过滤器可以通过运行时特性标志 enabled 配置字段进行启用或禁用。

Original Destination

Linux

当连接已被 iptables REDIRECT 目标重定向，或者被 iptables TPROXY 目标结合设置侦听器的“透明”选项重定向时，原始目标侦听器过滤器会读取 SO_ORIGINAL_DST 套接字选项集。

Windows

当连接被应用于容器端点的 HNS 策略重定向时，原始目标侦听器过滤器会读取设置的 SO_ORIGINAL_DST 套接字选项。要使此过滤器正常工作，必须在侦听器上设置 traffic_direction。这意味着需要一个单独的侦听器来处理入站和出站流量。

重定向不适用于所有类型的网络流量。支持重定向的数据包类型如下表所示：

• TCP/IPv4
• UDP
• 原始 UDPv4，无标头包含选项
• 原始 ICMP

有关详细信息，请参阅使用绑定或连接重定向

注意 在撰写本文时（2021 年 2 月），操作系统对原始目标的支持仅通过 Windows 预览体验计划。 该功能将在即将发布的 Windows Server 版本中得到全面支持，请参阅 Windows Server 发布信息。

Envoy 中的后续处理将恢复的目标地址视为连接的本地地址，而不是侦听器正在侦听的地址。此外， 原始目标集群 可用于将 HTTP 请求或 TCP 连接转发到恢复的目标地址。

内部监听器

原始目标侦听器过滤器读取由 内部侦听器 而不是系统套接字选项处理的用户空间套接字上的动态元数据和过滤器状态对象。

目标地址的动态元数据应放置在字段 local 下的键 envoy.filters.listener.original_dst 中，并应包含带有 IP 和端口地址的字符串。如果没有动态元数据，则参考过滤器状态。

该过滤器使用的过滤状态对象是：

• envoy.filters.listener.original_dst.local_ip 为目标地址
• envoy.filters.listener.original_dst.source_ip 为源地址

请注意 internal upstream transport 应用于将动态元数据从端点主机传递到套接字元数据和(或)通过用户空间套接字与上游连接共享的过滤器状态对象到内部侦听器。

• 此过滤器 URL 类型应配置为type.googleapis.com/envoy.extensions.filters.listener.original_dst.v3.OriginalDst。
• v3 API 参考

Original Source

• 此过滤器 URL 类型应配置为type.googleapis.com/envoy.extensions.filters.listener.original_src.v3.OriginalSrc。
• 监听器过滤器 v3 API 参考

原始源侦听器过滤器会在 Envoy 的上游复制连接的下游远程地址。例如，如果下游连接使用 IP 地址 10.1.2.3 连接到 Envoy，则 Envoy 将使用源 IP 10.1.2.3 连接到上游。

注意 Windows 不支持此过滤器。

注意 Linux 上需要 CAP_NET_ADMIN 功能。

与 Proxy Protocol 交互

如果连接的源地址尚未转换或代理，则 Envoy 可以简单地使用现有的连接信息来构建正确的下游远程地址。但是，如果不是这样，则可以使用 代理协议过滤器 来提取下游远程地址。

IP 版本支持

该过滤器支持 IPv4 和 IPv6 地址。请注意，上游连接必须支持使用的版本。

额外设置

使用的下游远程地址很可能是全局可路由的。默认情况下，从上游主机返回该地址的数据包不会通过 Envoy 路由。必须配置网络以强制将 IP 被 Envoy 复制的任何流量路由回 Envoy 主机。

如果 Envoy 和上游位于同一主机上, 例如在 sidecar 部署中，则可以使用 iptables 和路由规则来确保正确的行为。过滤器具有无符号整数配置mark。将其设置为 X 会导致 Envoy 使用值 X 标记来自此侦听器的所有上游数据包。请注意，如果将mark设置为 0，Envoy 将不会标记上游数据包。

我们可以使用以下命令集来确保所有标有 X（示例中假设为 123）的 ipv4 和 ipv6 流量都能正确路由。请注意，此示例假设 eth0 是默认出站接口。

1
2
3
4
5
6
7
8
9

iptables  -t mangle -I PREROUTING -m mark     --mark 123 -j CONNMARK --save-mark
iptables  -t mangle -I OUTPUT     -m connmark --mark 123 -j CONNMARK --restore-mark
ip6tables -t mangle -I PREROUTING -m mark     --mark 123 -j CONNMARK --save-mark
ip6tables -t mangle -I OUTPUT     -m connmark --mark 123 -j CONNMARK --restore-mark
ip rule add fwmark 123 lookup 100
ip route add local 0.0.0.0/0 dev lo table 100
ip -6 rule add fwmark 123 lookup 100
ip -6 route add local ::/0 dev lo table 100
echo 1 > /proc/sys/net/ipv4/conf/eth0/route_localnet

监听器配置示例

以下示例将 Envoy 配置为对端口 8888 上的所有连接使用原始源。它使用代理协议来确定下游远程地址。所有上游数据包都标记为 123。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

listeners:
- address:
    socket_address:
      address: 0.0.0.0
      port_value: 8888
  listener_filters:
    - name: envoy.filters.listener.proxy_protocol
      typed_config:
        "@type": type.googleapis.com/envoy.extensions.filters.listener.proxy_protocol.v3.ProxyProtocol
    - name: envoy.filters.listener.original_src
      typed_config:
        "@type": type.googleapis.com/envoy.extensions.filters.listener.original_src.v3.OriginalSrc
        mark: 123

Proxy Protocol

此监听过滤器增加了对 HAProxy 代理协议 的支持。

在此模式下，下游连接假定来自代理，代理将原始坐标（IP、PORT）放入连接字符串中。然后，Envoy 提取这些并将它们用作远程地址。

在代理协议 v2 中，存在可选的扩展 (TLV) 标签的概念。如果将 TLV 的类型添加到过滤器的配置中，则 TLV 将作为具有用户指定密钥的动态元数据发出。

此实现支持版本 1 和版本 2，它会根据每个连接自动确定存在哪个版本。注意：如果启用了过滤器，则代理协议必须存在于连接上（版本 1 或版本 2），标准不允许通过解析来确定它是否存在。

如果存在协议错误或不受支持的地址系列（例如 AF_UNIX），则连接将关闭并抛出错误。

• 此过滤器应配置为 URL 类型type.googleapis.com/envoy.extensions.filters.listener.proxy_protocol.v3.ProxyProtocol。
• v3 API 参考

统计数据

该过滤器发出以下统计数据：

TLS Inspector

TLS 检查器侦听器过滤器允许检测传输是否显示为 TLS 或纯文本，如果是 TLS，它会检测来自客户端的 Server Name Indication 和/或 应用层协议协商。这可用于通过 FilterChainMatch 的 server_names 和/或 application_protocols 选择 FilterChain。

• SNI
• 此过滤器应使用类型 URL type.googleapis.com/envoy.extensions.filters.listener.tls_inspector.v3.TlsInspector 配置。
• v3 API 参考

例子

示例过滤器配置可能是：

1
2
3
4

listener_filters:
- name: tls_inspector
  typed_config:
    "@type": type.googleapis.com/envoy.extensions.filters.listener.tls_inspector.v3.TlsInspector

统计数据

此过滤器有一个以 tls_inspector 为根的统计树，其统计数据如下：

运行时

连接限制过滤器可以通过“启用”配置字段标记运行时功能。