UDP 代理 (proto)

此扩展的限定名称为 envoy.filters.udp_listener.udp_proxy

注意

此扩展旨在对不受信任的下游流量具有鲁棒性。它假设上游是可信的。

提示

此扩展扩展并可与以下扩展类别一起使用

envoy.filters.udp_listener

此扩展必须使用以下类型 URL 之一进行配置

type.googleapis.com/envoy.extensions.filters.udp.udp_proxy.v3.UdpProxyConfig

UDP 代理配置概述.

extensions.filters.udp.udp_proxy.v3.UdpProxyConfig

[extensions.filters.udp.udp_proxy.v3.UdpProxyConfig proto]

UDP 代理过滤器的配置。

{
  "stat_prefix": ...,
  "cluster": ...,
  "matcher": {...},
  "idle_timeout": {...},
  "use_original_src_ip": ...,
  "hash_policies": [],
  "upstream_socket_config": {...},
  "use_per_packet_load_balancing": ...,
  "access_log": [],
  "proxy_access_log": [],
  "session_filters": [],
  "tunneling_config": {...},
  "access_log_options": {...}
}

stat_prefix: (string, REQUIRED) 在发出 UDP 代理过滤器统计信息时使用的统计信息前缀。

cluster

(string) 要连接的上游集群。此字段已弃用，改为使用 matcher.

cluster 和 matcher 中必须设置其中一个。

matcher

(.xds.type.matcher.v3.Matcher) 在为传入请求解析路由操作时要使用的匹配树。有关更多信息，请参阅路由.

警告

此 API 功能目前正在开发中。标记为正在开发中的 API 功能不被视为稳定，不受威胁模型的保护，不受安全团队的支持，并且可能会发生重大更改。在了解所有上述要点之前，请勿使用此功能。

cluster 和 matcher 中必须设置其中一个。

idle_timeout: (Duration) 会话的空闲超时。空闲定义为会话之间没有数据报接收或发送。如果未指定，默认值为 1 分钟。

use_original_src_ip: (bool) 在将数据包发送到上游主机时，使用远程下游 IP 地址作为发送方 IP 地址。此选项要求 Envoy 在 Linux 上使用 CAP_NET_ADMIN 功能运行。并且必须在 Linux 内核上启用 IPv6 堆栈。此选项不会保留远程下游端口。如果启用此选项，则已发送数据报的 IP 地址将更改为远程下游 IP 地址。这意味着 Envoy 不会收到上游主机发送的数据包，因为上游主机将使用远程下游 IP 地址作为目标地址发送数据包。如果上游主机端存在路由规则，则所有数据包将直接路由到远程下游。有两种选择可以将数据包返回到远程下游。第一个是使用 DSR（直接服务器返回）。另一个是在运行 Envoy 的主机上配置路由规则，以将所有数据包转发回 Envoy，并在运行 Envoy 的主机上配置 iptables 规则，以将所有来自上游主机的数据包转发到 Envoy 进程，以便 Envoy 可以将数据包转发到下游。如果平台不支持此选项，Envoy 将引发配置错误。

hash_policies: (repeated extensions.filters.udp.udp_proxy.v3.UdpProxyConfig.HashPolicy) UDP 代理哈希策略的可选配置。如果未设置 hash_policies，则基于哈希的负载均衡算法将随机选择主机。目前，哈希策略的数量限制为 1 个。

upstream_socket_config: (config.core.v3.UdpSocketConfig) 上游套接字的 UDP 套接字配置。 prefer_gro 的默认值为上游套接字为 true，因为假设数据报将从单个源接收。

use_per_packet_load_balancing: (bool) 对每个接收到的数据块执行每数据包负载均衡（上游主机选择）。如果未指定，则默认值为 false，这意味着每个数据块都将转发到为该“会话”（由源 IP/端口和本地 IP/端口标识）接收到的第一个块选择的上传主机。只能使用 use_per_packet_load_balancing 或 session_filters 之一。

access_log: (repeated config.accesslog.v3.AccessLog) UDP 代理发出的会话访问日志的配置。请注意，某些 UDP 特定数据将作为动态元数据发出。

proxy_access_log: (repeated config.accesslog.v3.AccessLog) UDP 代理发出的代理访问日志的配置。请注意，某些 UDP 特定数据将作为动态元数据发出。

session_filters

(repeated extensions.filters.udp.udp_proxy.v3.UdpProxyConfig.SessionFilter) 每个 UDP 会话将运行的可选会话过滤器。只能使用 use_per_packet_load_balancing 或 session_filters 之一。

提示

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

tunneling_config: (extensions.filters.udp.udp_proxy.v3.UdpProxyConfig.UdpTunnelingConfig) 如果设置，此配置将配置 UDP 隧道。参阅在 HTTP 中代理 UDP。有关更多信息，请参阅 UDP 代理和 HTTP 升级文档。

access_log_options: (extensions.filters.udp.udp_proxy.v3.UdpProxyConfig.UdpAccessLogOptions) UDP 代理的其他访问日志选项。

extensions.filters.udp.udp_proxy.v3.UdpProxyConfig.HashPolicy

[extensions.filters.udp.udp_proxy.v3.UdpProxyConfig.HashPolicy proto]

指定 UDP 哈希策略。数据包可以通过哈希策略进行路由。

{
  "source_ip": ...,
  "key": ...
}

source_ip

(bool) 源 IP 将用于计算基于哈希的负载均衡算法使用的哈希值。

source_ip 和 key 中必须设置其中一个。

key

(string) 给定的键将用于计算基于哈希的负载均衡算法使用的哈希值。在某些情况下，需要将不同的 UDP 流共同定向到所选的端点集。一个可能的用例是 VoIP 电话，其中媒体 (RTP) 及其相应的控制 (RTCP) 属于同一逻辑会话，尽管它们在独立的流中传输。为了确保这些流对在会话级别（而不是单个流级别）进行负载均衡，动态创建的监听器可以对会话中的每个流使用相同的哈希键。

source_ip 和 key 中必须设置其中一个。

extensions.filters.udp.udp_proxy.v3.UdpProxyConfig.SessionFilter

[extensions.filters.udp.udp_proxy.v3.UdpProxyConfig.SessionFilter proto]

UDP 会话过滤器的配置。

{
  "name": ...,
  "typed_config": {...},
  "config_discovery": {...}
}

name: (string, REQUIRED) 过滤器配置的名称。

typed_config

(Any) 依赖于正在实例化的过滤器的过滤器特定配置。有关更多文档，请参阅支持的过滤器。

typed_config 和 config_discovery 中只能设置其中一个。

config_discovery

(config.core.v3.ExtensionConfigSource) 扩展配置发现服务的配置源说明符。在发生故障并且没有默认配置的情况下，UDP 会话将被删除。

typed_config 和 config_discovery 中只能设置其中一个。

extensions.filters.udp.udp_proxy.v3.UdpProxyConfig.UdpTunnelingConfig

[extensions.filters.udp.udp_proxy.v3.UdpProxyConfig.UdpTunnelingConfig proto]

用于通过其他传输或应用程序层隧道 UDP 的配置。目前支持通过 HTTP/2 进行隧道连接。

{
  "proxy_host": ...,
  "proxy_port": {...},
  "target_host": ...,
  "default_target_port": ...,
  "use_post": ...,
  "post_path": ...,
  "retry_options": {...},
  "headers_to_add": [],
  "buffer_options": {...},
  "propagate_response_headers": ...,
  "propagate_response_trailers": ...
}

proxy_host

(string, REQUIRED) 要在合成 CONNECT 标头中发送到上游代理的主机名。如果设置了此字段，它将评估命令运算符，否则将按原样返回主机名。

示例：使用过滤器状态动态设置主机名

tunneling_config:
  proxy_host: "%FILTER_STATE(proxy.host.key:PLAIN)%"

proxy_port: (UInt32Value) 要添加到 HTTP 请求 URI 中的可选端口值。此值可以通过为过滤器状态键 udp.connect.proxy_port 设置所需的端口值来按会话覆盖。

target_host

(字符串, 必需) 发送到上游代理的合成 CONNECT 标头中的目标主机。如果设置了此字段，它将评估命令运算符，否则将按原样返回主机名。

示例：使用过滤器状态动态设置目标主机

tunneling_config:
  target_host: "%FILTER_STATE(target.host.key:PLAIN)%"

default_target_port: (uint32) 发送到上游代理的 CONNECT 标头中的默认目标端口。此值可以通过为过滤器状态键 udp.connect.target_port 设置必需的端口值来在每个会话中覆盖。

use_post: (布尔值) 使用 POST 方法而不是 CONNECT 方法来隧道 UDP 流。

注意

如果设置了 use_post，上游流不符合 connect-udp RFC，而是 POST 请求。标头中使用的路径将从 post_path 字段设置，并且标头不会包含目标主机和目标端口，因为 connect-udp 协议要求这样做。此标志应谨慎使用。

post_path: (字符串) 与 POST 方法一起使用的路径。默认路径为 /。如果指定了 post 路径并且 use_post 字段不为真，它将被拒绝。

retry_options: (extensions.filters.udp.udp_proxy.v3.UdpProxyConfig.UdpTunnelingConfig.RetryOptions) 可选的重试选项，如果连接到上游失败。

headers_to_add

(重复 config.core.v3.HeaderValueOption) 上游代理的额外请求标头。无法覆盖 :-prefixed 伪标头或 Host: 标头。如果在值模板中设置了添加的标头的值，则它们将评估命令运算符。

示例：使用本地端口动态设置标头

headers_to_add:
- header:
    key: original_dst_port
    value: "%DOWNSTREAM_LOCAL_PORT%"

buffer_options: (extensions.filters.udp.udp_proxy.v3.UdpProxyConfig.UdpTunnelingConfig.BufferOptions) 如果配置，过滤器将在等待上游准备就绪的情况下缓冲数据报，无论是连接过程期间还是由于上游缓冲水印。如果未配置此字段，则不会进行缓冲，并且在未准备好上游时到达的下游数据报将被丢弃。如果设置了此字段但未配置选项，则将应用默认值，如 BufferOptions 中所述。

propagate_response_headers: (布尔值) 将响应标头保存到下游信息过滤器状态，供会话过滤器使用。过滤器状态键为 envoy.udp_proxy.propagate_response_headers。

propagate_response_trailers: (布尔值) 将响应尾部保存到下游信息过滤器状态，供会话过滤器使用。过滤器状态键为 envoy.udp_proxy.propagate_response_trailers。

extensions.filters.udp.udp_proxy.v3.UdpProxyConfig.UdpTunnelingConfig.BufferOptions

[extensions.filters.udp.udp_proxy.v3.UdpProxyConfig.UdpTunnelingConfig.BufferOptions proto]

UDP 数据报缓冲的配置。

{
  "max_buffered_datagrams": {...},
  "max_buffered_bytes": {...}
}

max_buffered_datagrams: (UInt32Value) 如果设置，过滤器将仅缓冲数据报，直到达到请求的限制，并在新数据报到达时缓冲区包含 max_buffered_datagrams 值时，将丢弃新的 UDP 数据报。如果未设置，则默认值为 1024 个数据报。

max_buffered_bytes: (UInt64Value) 如果设置，过滤器将仅缓冲数据报，直到达到请求的总缓冲字节限制，并在新数据报到达时缓冲区包含 max_buffered_datagrams 值时，将丢弃新的 UDP 数据报。如果未设置，则默认值为 16,384 (16KB)。

extensions.filters.udp.udp_proxy.v3.UdpProxyConfig.UdpTunnelingConfig.RetryOptions

[extensions.filters.udp.udp_proxy.v3.UdpProxyConfig.UdpTunnelingConfig.RetryOptions proto]

{
  "max_connect_attempts": {...}
}

max_connect_attempts: (UInt32Value) 在放弃之前将尝试的失败连接尝试的最大次数。如果未指定参数，将尝试 1 次连接。

extensions.filters.udp.udp_proxy.v3.UdpProxyConfig.UdpAccessLogOptions

[extensions.filters.udp.udp_proxy.v3.UdpProxyConfig.UdpAccessLogOptions proto]

{
  "access_log_flush_interval": {...},
  "flush_access_log_on_tunnel_connected": ...
}

access_log_flush_interval: (持续时间) 刷新访问日志的间隔。默认情况下，UDP 代理仅在会话结束时刷新一个访问日志。如果设置了此字段，UDP 代理将以指定的间隔定期刷新访问日志。此字段不需要启用隧道连接访问日志记录，反之亦然。间隔必须至少为 1 毫秒。

flush_access_log_on_tunnel_connected: (布尔值) 如果设置为 true 并且配置了 UDP 隧道，则当 UDP 代理已成功与上游建立连接隧道时，将刷新访问日志。如果连接失败，则不会刷新访问日志。