HTTP 连接管理器 (proto)

此扩展的限定名称为 envoy.filters.network.http_connection_manager

注意

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

提示

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

envoy.filters.network

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

type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager

HTTP 连接管理器配置概述.

extensions.filters.network.http_connection_manager.v3.HttpConnectionManager

[extensions.filters.network.http_connection_manager.v3.HttpConnectionManager proto]

{
  "codec_type": ...,
  "stat_prefix": ...,
  "rds": {...},
  "route_config": {...},
  "scoped_routes": {...},
  "http_filters": [],
  "add_user_agent": {...},
  "tracing": {...},
  "common_http_protocol_options": {...},
  "http1_safe_max_connection_duration": ...,
  "http_protocol_options": {...},
  "http2_protocol_options": {...},
  "http3_protocol_options": {...},
  "server_name": ...,
  "server_header_transformation": ...,
  "scheme_header_transformation": {...},
  "max_request_headers_kb": {...},
  "stream_idle_timeout": {...},
  "request_timeout": {...},
  "request_headers_timeout": {...},
  "drain_timeout": {...},
  "delayed_close_timeout": {...},
  "access_log": [],
  "access_log_flush_interval": {...},
  "flush_access_log_on_new_request": ...,
  "access_log_options": {...},
  "use_remote_address": {...},
  "xff_num_trusted_hops": ...,
  "original_ip_detection_extensions": [],
  "early_header_mutation_extensions": [],
  "internal_address_config": {...},
  "skip_xff_append": ...,
  "via": ...,
  "generate_request_id": {...},
  "preserve_external_request_id": ...,
  "always_set_request_id_in_response": ...,
  "forward_client_cert_details": ...,
  "set_current_client_cert_details": {...},
  "proxy_100_continue": ...,
  "upgrade_configs": [],
  "normalize_path": {...},
  "merge_slashes": ...,
  "path_with_escaped_slashes_action": ...,
  "request_id_extension": {...},
  "local_reply_config": {...},
  "strip_matching_host_port": ...,
  "strip_any_host_port": ...,
  "stream_error_on_invalid_http_message": {...},
  "strip_trailing_host_dot": ...,
  "proxy_status_config": {...},
  "append_x_forwarded_port": ...,
  "append_local_overload": ...,
  "add_proxy_protocol_connection_state": {...}
}

codec_type: (extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.CodecType) 提供连接管理器应使用的编解码器类型。

stat_prefix: (string, REQUIRED) 用于在为连接管理器发出统计信息时使用的可读前缀。有关更多信息，请参阅统计信息文档。

rds

(extensions.filters.network.http_connection_manager.v3.Rds) 连接管理器的路由表将通过 RDS API 动态加载。

必须准确设置 rds、route_config 或 scoped_routes 之一。

route_config

(config.route.v3.RouteConfiguration) 连接管理器的路由表是静态的，并在此属性中指定。

必须准确设置 rds、route_config 或 scoped_routes 之一。

scoped_routes

(extensions.filters.network.http_connection_manager.v3.ScopedRoutes) 将根据请求属性（例如，标头的值）动态将路由表分配给每个请求。“路由范围”（即路由表）和“范围键”在该消息中指定。

必须准确设置 rds、route_config 或 scoped_routes 之一。

http_filters: (repeated extensions.filters.network.http_connection_manager.v3.HttpFilter) 构成对连接管理器发出的请求的过滤器链的各个 HTTP 过滤器的列表。顺序很重要，因为过滤器在请求事件发生时按顺序进行处理。

add_user_agent: (BoolValue) 连接管理器是否操纵 :path 和 x-envoy-downstream-service-cluster 标头。有关更多信息，请参阅链接文档。默认为 false。

tracing: (extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.Tracing) 对象的存在定义连接管理器是否将跟踪数据发送到配置的跟踪提供者。

common_http_protocol_options

(config.core.v3.HttpProtocolOptions) 连接管理器处理的 HTTP 请求的附加设置。这些将适用于 HTTP1 和 HTTP2 请求。

注意

此字段应在存在不可信的下游时配置。

不可信环境的示例配置

common_http_protocol_options:
  headers_with_underscores_action: REJECT_REQUEST
  idle_timeout: 900s

http1_safe_max_connection_duration

(bool) 如果设置为 true，Envoy 将不会在 common_http_protocol_options.max_connection_duration 超过之后为下游 HTTP1 连接启动排空计时器。相反，Envoy 将等待下一个下游请求，在响应标头中添加 connection:close，然后在流结束之后关闭连接。

此行为符合 RFC 9112 第 9.6 节

如果设置为 false，max_connection_duration 将导致 Envoy 进入 HTTP1 的正常排空序列，Envoy 最终关闭连接（一旦没有活动流）。

如果 max_connection_duration 未设置，则无效。默认为 false。

http_protocol_options: (config.core.v3.Http1ProtocolOptions) 传递到 HTTP/1 编解码器的其他 HTTP/1 设置。

http2_protocol_options

(config.core.v3.Http2ProtocolOptions) 直接传递到 HTTP/2 编解码器的其他 HTTP/2 设置。

注意

此字段应在存在不可信的下游时配置。

不可信环境的示例配置

http2_protocol_options:
  initial_connection_window_size: 1048576.0
  initial_stream_window_size: 65536.0
  max_concurrent_streams: 100.0

http3_protocol_options: (config.core.v3.Http3ProtocolOptions) 直接传递到 HTTP/3 编解码器的其他 HTTP/3 设置。

server_name: (string) 连接管理器将在响应中写入服务器标头的可选覆盖。如果未设置，则默认值为 envoy。

server_header_transformation: (extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.ServerHeaderTransformation) 定义要对响应路径上的 Server 标头应用的操作。默认情况下，Envoy 将使用 server_name 中指定的值覆盖标头。

scheme_header_transformation: (config.core.v3.SchemeHeaderTransformation) 允许对请求路径上的 :scheme 标头进行显式转换。如果未设置，则应用 Envoy 的默认方案处理。

max_request_headers_kb

(UInt32Value) 进入连接的最大请求标头大小。如果未配置，则允许的最大请求标头的默认值为 60 KiB。可以通过设置运行时键 envoy.reloadable_features.max_request_headers_size_kb 来覆盖默认值。超出此限制的请求将收到 431 响应。

注意：目前一些协议编解码器对单个标头的最大大小有限制: HTTP/2（使用 nghttp2 时）将单个标头限制在约 100kb。HTTP/3 将单个标头限制在约 1024kb。

stream_idle_timeout

(Duration) 连接管理器管理的连接的流空闲超时。如果未指定，则默认为 5 分钟。选择默认值是为了不干扰配置中可能存在的任何较小的已配置超时（这些超时可能在引入此功能之前存在），同时为没有 FIN 终止的 TCP 连接引入鲁棒性。

此空闲超时适用于新流，并且可以通过路由级 idle_timeout 覆盖。即使在覆盖适用的流中，在接收初始请求标头之前，stream_idle_timeout 仍然适用。每次为流处理标头或数据的编码/解码事件时，计时器都会重置。如果超时触发，则如果未收到上游响应标头，则流将使用 408 请求超时错误代码终止，否则将发生流重置。

此超时还指定 Envoy 等待对等方打开足够窗口以写入任何剩余流数据的时长，一旦所有流数据（本地结束流为 true）已被缓冲并等待可用窗口。换句话说，此超时防止对等方不释放足够的窗口以完全写入流，即使所有数据已在可用的流控制窗口内代理。如果在这种情况下超时，则 tx_flush_timeout 计数器将增加。请注意，max_stream_duration 不适用于这种情况。

如果配置了超载操作 “envoy.overload_actions.reduce_timeouts”，此超时将根据 HTTP_DOWNSTREAM_STREAM_IDLE 的值进行缩放。

请注意，即使流的线缆流量并非空闲，也可能发生空闲超时，这是因为连接管理器呈现的事件粒度。例如，在接收非常大的请求标头时，可能出现线缆上定期到达流量，而连接管理器只能观察标头结束事件，因此流仍然可能发生空闲超时。

值为 0 将完全禁用连接管理器流空闲超时，但每条路由的空闲超时覆盖将继续应用。

注意

此字段应在存在不可信的下游时配置。

不可信环境的示例配置

stream_idle_timeout: 300s

request_timeout

(Duration) Envoy 等待接收完整请求的时间。计时器在请求开始时启动，并在请求的最后一个字节发送到上游（即所有解码过滤器都处理了请求）或响应开始时解除。如果未指定或设置为 0，则此超时将被禁用。

注意

此字段应在存在不可信的下游时配置。

此超时与流式请求不兼容。

不可信环境的示例配置

request_timeout: 300s

request_headers_timeout

(Duration) Envoy 等待接收请求标头的时间。计时器在接收标头的第一个字节时启动，并在接收标头的最后一个字节时解除。如果未指定或设置为 0，则此超时将被禁用。

注意

此字段应在存在不可信的下游时配置。

不可信环境的示例配置

request_headers_timeout: 10s

drain_timeout: (Duration) Envoy 在发送 HTTP/2 “关闭通知”（带有最大流 ID 的 GOAWAY 帧）和最终 GOAWAY 帧之间等待的时间。这样做是为了让 Envoy 为与最终 GOAWAY 帧竞争的新流提供一个宽限期。在此宽限期内，Envoy 将继续接受新流。宽限期结束后，将发送最终 GOAWAY 帧，Envoy 将开始拒绝新流。当连接达到空闲超时、达到 max_connection_duration 或在服务器一般清空期间，将发生清空。如果未指定此选项，则默认宽限期为 5000 毫秒（5 秒）。

delayed_close_timeout

(Duration) 延迟关闭超时适用于 HTTP 连接管理器管理的下游连接。它定义为在本地启动连接关闭处理后的一段宽限期，在此期间 Envoy 将等待对端关闭（即 Envoy 从下游连接接收到 TCP FIN/RST）然后再关闭与该连接关联的套接字。注意：即使与下游连接关联的套接字正在等待写入缓冲区的刷新，也会执行此超时。但是，对套接字写入数据的任何进度都将重新启动与该超时关联的计时器。这意味着此状态下套接字的总宽限期将为 + 。

延迟 Envoy 的连接关闭并让对端有机会启动关闭序列可以缓解在检测到远程关闭（通过套接字写入（））后，下游客户端未清空/处理连接接收缓冲区中的数据时存在的竞争条件。这种竞争会导致此类客户端无法处理 Envoy 发送的响应代码，从而导致下游处理错误。

如果超时触发，Envoy 将关闭连接的套接字。

如果未指定此选项，则默认超时为 1000 毫秒。

注意

为了在避免上述竞争条件方面发挥作用，此超时必须至少设置为 + <100ms to account for a reasonable “worst” case processing time for a full iteration of Envoy’s event loop>。

警告

值为 0 将完全禁用延迟关闭处理。禁用后，下游连接的套接字将在写入刷新完成后立即关闭，如果写入刷新未完成，则永远不会关闭。

access_log: (repeated config.accesslog.v3.AccessLog) 连接管理器发出的 HTTP 访问日志的配置。

access_log_flush_interval: (Duration) 以上访问日志的刷新间隔。

注意

此字段已弃用，建议使用 access_log_flush_interval。请注意，如果同时指定了此字段和 access_log_flush_interval，则前者（已弃用字段）将被忽略。

flush_access_log_on_new_request: (bool) 如果设置为 true，HCM 将在接收到新的 HTTP 请求后，在评估请求标头后且在遍历 HTTP 过滤器链之前刷新访问日志。

注意

此字段已弃用，建议使用 flush_access_log_on_new_request。请注意，如果同时指定了此字段和 flush_access_log_on_new_request，则前者（已弃用字段）将被忽略。

access_log_options: (extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.HcmAccessLogOptions) HTTP 连接管理器的其他访问日志选项。

use_remote_address

(BoolValue) 如果设置为 true，连接管理器将使用客户端连接的真实远程地址来确定内部与外部来源，并操纵各种标头。如果设置为 false 或缺失，连接管理器将使用 x-forwarded-for HTTP 标头。有关更多信息，请参阅 x-forwarded-for、x-envoy-internal 和 x-envoy-external-address 的文档。

注意

此字段应在存在不可信的下游时配置。

不可信环境的示例配置

use_remote_address: true

xff_num_trusted_hops: (uint32) 在确定源客户端的 IP 地址时，要信任的 x-forwarded-for HTTP 标头右侧的额外入口代理跃点的数量。如果未指定此选项，则默认值为零。有关更多信息，请参阅 x-forwarded-for 的文档。

original_ip_detection_extensions

(repeated config.core.v3.TypedExtensionConfig) 原始 IP 检测扩展的配置。

配置后，这些扩展将与请求标头和有关下游连接的信息（例如直接连接的地址）一起调用。然后，每个扩展将使用这些参数来确定请求的有效远程地址。如果扩展无法检测到原始 IP 地址且未配置为拒绝请求，则 HCM 将尝试剩余的扩展，直到有一个成功或拒绝请求。如果请求未被拒绝且没有任何扩展成功，则 HCM 将回退到使用远程地址。

警告

扩展不能与 use_remote_address 或 xff_num_trusted_hops 结合使用。

提示

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

early_header_mutation_extensions

(repeated config.core.v3.TypedExtensionConfig) 早期标头变异扩展的配置。

配置后，这些扩展将在任何路由、跟踪或任何过滤器处理之前调用。每个扩展将按照其配置的顺序应用。如果同一标头被多个扩展变异，则最后一个扩展将获胜。

提示

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

envoy.http.early_header_mutation.header_mutation

internal_address_config

(extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.InternalAddressConfig) 配置哪些网络地址被视为内部地址，用于统计和标头清理目的。如果未指定，则只有 RFC1918 IP 地址将被视为内部地址。有关内部/外部地址的更多信息，请参阅 x-envoy-internal 的文档。

警告

从 Envoy 1.33.0 开始，将不再有 IP 地址被视为受信任地址。如果您有工具（例如私有网络上的探测器）需要被视为受信任地址（例如更改任意 x-envoy 标头），您将必须手动包含这些地址或 CIDR 范围，例如

cidr_ranges:
    address_prefix: 10.0.0.0
    prefix_len: 8
cidr_ranges:
    address_prefix: 192.168.0.0
    prefix_len: 16
cidr_ranges:
    address_prefix: 172.16.0.0
    prefix_len: 12
cidr_ranges:
    address_prefix: 127.0.0.1
    prefix_len: 32
cidr_ranges:
    address_prefix: fd00::
    prefix_len: 8
cidr_ranges:
    address_prefix: ::1
    prefix_len: 128

skip_xff_append: (bool) 如果设置，Envoy 将不会将远程地址追加到 x-forwarded-for HTTP 标头。这可以与在 HTTP 连接管理器变异请求标头后显式操作 XFF 的 HTTP 过滤器结合使用。虽然 use_remote_address 也会抑制 XFF 添加，但它会对日志记录和其他 Envoy 对远程地址的使用产生影响，因此应在仅打算省略 XFF 添加时使用 skip_xff_append。

via: (string) 要追加到请求和响应标头的 Via 标头值。如果此值为空，则不会追加 Via 标头。

generate_request_id: (BoolValue) 如果连接管理器不生成 x-request-id 标头，则它是否将生成该标头。默认值为 true。生成随机 UUID4 非常昂贵，因此在不希望使用此功能的高吞吐量场景中，可以禁用它。

preserve_external_request_id: (bool) 连接管理器是否保留 x-request-id 标头（如果它被传递给边缘请求，边缘请求是指外部客户端到前端 Envoy 的请求），而不是将其重置，这是当前的 Envoy 行为。默认值为 false。

always_set_request_id_in_response: (bool) 如果设置，Envoy 将始终在响应中设置 x-request-id 标头。如果此选项为 false 或未设置，则请求 ID 仅在使用 x-envoy-force-trace 标头强制跟踪时返回响应。

forward_client_cert_details: (extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.ForwardClientCertDetails) 如何处理 x-forwarded-client-cert (XFCC) HTTP 标头。

set_current_client_cert_details: (extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.SetCurrentClientCertDetails) 此字段仅在 forward_client_cert_details 为 APPEND_FORWARD 或 SANITIZE_SET 且客户端连接为 mTLS 时有效。它指定要转发的客户端证书中的字段。请注意，在 x-forwarded-client-cert 标头中，Hash 始终设置，并且当客户端证书呈现 URI 类型主体备用名称值时，By 始终设置。

proxy_100_continue: (bool) 如果 proxy_100_continue 为 true，Envoy 将代理传入的“Expect: 100-continue”标头到上游，并将“100 Continue”响应转发到下游。如果此选项为 false 或未设置，Envoy 将改为剥离“Expect: 100-continue”标头，并自行发送“100 Continue”响应。

upgrade_configs: (repeated extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.UpgradeConfig)

normalize_path: (BoolValue) 在 HTTP 过滤器或路由处理任何请求之前，是否应根据 RFC 3986 规范化路径？这也会影响上游的 :path 标头。对于未通过此检查的路径，Envoy 将对格式错误的路径返回 400。当前默认值为 false，但将来将默认值为 true。如果未指定，此值可能会被运行时变量 http_connection_manager.normalize_path 覆盖。有关规范化的详细信息，请参见规范化和比较。请注意，Envoy 不执行大小写规范化

merge_slashes: (bool) 确定在 HTTP 过滤器或路由处理任何请求之前，是否将路径中相邻的斜杠合并为一个。这也会影响上游的 :path 标头。如果不设置此选项，则具有 //dir///file 路径的传入请求将不会与具有 prefix 匹配设置为 /dir 的路由匹配。默认值为 false。请注意，斜杠合并不是 HTTP 规范的一部分，它是为了方便而提供的。

path_with_escaped_slashes_action: (extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.PathWithEscapedSlashesAction) 当请求 URL 路径包含转义斜杠序列 (%2F, %2f, %5C 和 %5c) 时要采取的操作。默认值可以被 http_connection_manager.path_with_escaped_slashes_action 运行时变量覆盖。 http_connection_manager.path_with_escaped_slashes_action_sampling 运行时变量可用于将操作应用于所有请求的一部分。

request_id_extension

(extensions.filters.network.http_connection_manager.v3.RequestIDExtension) 请求 ID 扩展的配置。这包括生成、验证和关联的跟踪操作等操作。如果为空，则使用具有默认参数的 UuidRequestIdConfig 默认扩展。有关它执行的操作的详细信息，请参见该扩展的文档。通过在此处显式配置它，可以实现对默认扩展的配置进行自定义。例如，要禁用跟踪原因打包，可以使用以下配置

typed_config:
  "@type": type.googleapis.com/envoy.extensions.request_id.uuid.v3.UuidRequestIdConfig
  pack_trace_reason: false

提示

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

envoy.request_id.uuid

local_reply_config: (extensions.filters.network.http_connection_manager.v3.LocalReplyConfig) 用于自定义 Envoy 返回的本地回复的配置。它可以自定义状态码、正文文本和响应内容类型。如果未指定，则状态码和文本正文在 Envoy 中被硬编码，响应内容类型为纯文本。

strip_matching_host_port: (bool) 确定在 HTTP 过滤器或路由处理任何请求之前，是否应从 host/authority 标头中删除端口部分。只有当端口等于监听器的本地端口时才会删除端口。这会影响上游主机标头，除非方法为 CONNECT，在这种情况下，如果过滤器没有添加端口，则原始端口将在标头发送到上游之前恢复。如果不设置此选项，则具有 example:443 主机的传入请求将不会与具有域匹配设置为 example 的路由匹配。默认值为 false。请注意，端口删除不是 HTTP 规范的一部分，它是为了方便而提供的。只能设置 strip_matching_host_port 或 strip_any_host_port 之一。

strip_any_host_port: (bool) 确定在 HTTP 过滤器或路由处理任何请求之前，是否应从 host/authority 标头中删除端口部分。这会影响上游主机标头，除非方法为 CONNECT，在这种情况下，如果过滤器没有添加端口，则原始端口将在标头发送到上游之前恢复。如果不设置此选项，则具有 example:443 主机的传入请求将不会与具有域匹配设置为 example 的路由匹配。默认值为 false。请注意，端口删除不是 HTTP 规范的一部分，它是为了方便而提供的。只能设置 strip_matching_host_port 或 strip_any_host_port 之一。

stream_error_on_invalid_http_message

(BoolValue) 控制 Envoy 在从下游接收无效 HTTP 时如何表现。如果此选项为 false（默认值），Envoy 将在处理 HTTP 错误时保持谨慎，在接收到无效请求时终止 HTTP/1.1 和 HTTP/2 连接。如果此选项设置为 true，Envoy 将更加宽容，仅在 HTTP/2 情况下重置无效流，并在可能的情况下保持连接打开（如果整个请求在 HTTP/1.1 中被读取）。通常，这应该适用于接收可信流量的部署（L2 Envoy、公司内部网格）并且应该适用于接收不可信流量的部署（边缘部署）。

如果希望针对 HTTP/1 和 HTTP/2 的 invalid_http_message 采取不同的行为，则应使用新的 HTTP/1 选项 override_stream_error_on_invalid_http_message 或新的 HTTP/2 选项 override_stream_error_on_invalid_http_message，not 已弃用但名称类似的 stream_error_on_invalid_http_messaging

strip_trailing_host_dot: (bool) 确定在 HTTP 过滤器或路由处理任何请求之前，是否应从 host/authority 标头中删除主机后面的点。这会影响上游主机标头。如果不设置此选项，则具有 example.com. 主机的传入请求将不会与具有域匹配设置为 example.com 的路由匹配。默认值为 false。当传入请求包含一个包含端口号的 host/authority 标头时，设置此选项将删除主机部分（如果存在）后面的点，并将端口保留原样（例如，主机值 example.com.:443 将更新为 example.com:443）。

proxy_status_config: (extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.ProxyStatusConfig) Proxy-Status HTTP 响应标头配置。如果设置此配置，则将填充 Proxy-Status HTTP 响应标头字段。默认情况下，不会填充该字段。

append_x_forwarded_port: (bool) 使用客户端连接到 Envoy 的端口值附加 x-forwarded-port 标头。如果任何位于 Envoy 前面的可信代理已设置 x-forwarded-port 标头，则它将被忽略。

append_local_overload: (布尔值) 当负载管理器的触发条件满足时，添加 x-envoy-local-overloaded HTTP 头部。

add_proxy_protocol_connection_state: (BoolValue) HCM 是否将 ProxyProtocolFilterState 添加到连接生命周期过滤器状态。默认值为 true。如果 Envoy 对下游地址的视图可能与实际客户端地址不符，则应将其设置为 false，例如，如果 Envoy 前面还有其他代理。

extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.Tracing

[extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.Tracing proto]

{
  "client_sampling": {...},
  "random_sampling": {...},
  "overall_sampling": {...},
  "verbose": ...,
  "max_path_tag_length": {...},
  "custom_tags": [],
  "provider": {...},
  "spawn_upstream_span": {...}
}

client_sampling: (type.v3.Percent) 该 HTTP 连接管理器管理的请求中，如果设置了 x-client-trace-id 标头，将被强制跟踪的请求的百分比。此字段是 HTTP 连接管理器中运行时变量“tracing.client_enabled”的直接模拟。默认：100%

random_sampling: (type.v3.Percent) 该 HTTP 连接管理器管理的请求中，如果未由客户端请求或未强制执行，将被随机选择用于跟踪生成的请求的百分比。此字段是 HTTP 连接管理器中运行时变量“tracing.random_sampling”的直接模拟。默认：100%

overall_sampling: (type.v3.Percent) 该 HTTP 连接管理器管理的请求中，在应用所有其他采样检查（客户端定向、强制跟踪、随机采样）后将被跟踪的请求的百分比。此字段作为总配置采样率的上限。例如，将 client_sampling 设置为 100% 但 overall_sampling 设置为 1% 将导致只有 1% 的具有相应标头的客户端请求被强制跟踪。此字段是 HTTP 连接管理器中运行时变量“tracing.global_enabled”的直接模拟。默认：100%

verbose: (布尔值) 是否使用其他数据注释跨度。如果为真，跨度将包括流事件的日志。

max_path_tag_length: (UInt32Value) 从请求路径中提取并包含在 HttpUrl 标签中的最大长度。用于截断冗长的请求路径以满足跟踪后端的需要。默认：256

custom_tags: (重复 type.tracing.v3.CustomTag) 具有唯一标签名称的自定义标签列表，用于为活动跨度创建标签。

provider: (config.trace.v3.Tracing.Http) 外部跟踪提供程序的配置。如果未指定，则不会执行跟踪。

注意

请注意，envoy.tracers.opencensus 提供程序在 Envoy 生命周期内只能配置一次。任何尝试重新配置它或对不同的 HCM 过滤器使用不同的配置都将被拒绝。这种约束是 OpenCensus 本身固有的。它无法在 OpenCensus 方面没有更改的情况下克服。

spawn_upstream_span

(BoolValue) 如果为真，则为每个上游请求创建单独的跟踪跨度。如果此标志设置为 true，则跟踪提供程序将假定 Envoy 将是跟踪链中的独立跳跃，并可能根据此标志将跨度类型设置为客户端或服务器。这将弃用路由器中的 start_child_span。

用户应根据他们的跟踪提供程序和实际场景设置适当的值

如果 Envoy 用作 sidecar，并且用户希望将 sidecar 及其应用程序作为一个跳跃在跟踪链中，则此标志应设置为 false。另外，请确保路由器中的 start_child_span 未设置为 true。
如果 Envoy 用作网关或独立代理，或者用户希望将 sidecar 及其应用程序作为跟踪链中的不同跳跃，则此标志应设置为 true。
如果跟踪提供程序对跨度创建有明确的要求（如 SkyWalking），则此标志应设置为 true。

为了向后兼容，当前的默认值为 false。

Enum extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.Tracing.OperationName

[extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.Tracing.OperationName proto]

INGRESS: (DEFAULT) ⁣HTTP 侦听器用于入站/传入请求。

EGRESS: ⁣HTTP 侦听器用于出站/传出请求。

extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.InternalAddressConfig

[extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.InternalAddressConfig proto]

{
  "unix_sockets": ...,
  "cidr_ranges": []
}

unix_sockets: (布尔值) 是否应将 Unix 套接字地址视为内部地址。

cidr_ranges: (重复 config.core.v3.CidrRange) 被视为内部地址的 CIDR 范围列表。如果未设置，则 RFC1918 / RFC4193 IP 地址将被视为内部地址。

extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.SetCurrentClientCertDetails

[extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.SetCurrentClientCertDetails proto]

{
  "subject": {...},
  "cert": ...,
  "chain": ...,
  "dns": ...,
  "uri": ...
}

subject: (BoolValue) 是否转发客户端证书的主题。默认值为 false。

cert: (布尔值) 是否以 URL 编码的 PEM 格式转发整个客户端证书。这将出现在 XFCC 标头中，以逗号分隔其他值，值为 Cert=”PEM”。默认值为 false。

chain: (布尔值) 是否以 URL 编码的 PEM 格式转发整个客户端证书链（包括叶证书）。这将出现在 XFCC 标头中，以逗号分隔其他值，值为 Chain=”PEM”。默认值为 false。

dns: (布尔值) 是否转发客户端证书的 DNS 类型主题备用名称。默认值为 false。

uri: (布尔值) 是否转发客户端证书的 URI 类型主题备用名称。默认值为 false。

extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.UpgradeConfig

[extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.UpgradeConfig proto]

HTTP 升级的配置。对于每个所需的升级类型，必须添加一个 UpgradeConfig。

警告

当前的升级标头实现不处理多值升级标头。如果需要，将来可能会添加对多值标头的支持。

警告

当前的升级标头实现不适用于 HTTP/2 上游。

{
  "upgrade_type": ...,
  "filters": [],
  "enabled": {...}
}

upgrade_type: (字符串) 此升级的不区分大小写的名称，例如“websocket”。对于 upgrade_configs 中存在的每个升级类型，具有 Upgrade: [upgrade_type] 的请求将被代理到上游。

filters: (重复 extensions.filters.network.http_connection_manager.v3.HttpFilter) 如果存在，则表示将为此类型的升级创建的过滤器链。如果不存在过滤器，则将使用 HTTP 连接的过滤器链来执行此升级类型。

enabled: (BoolValue) 确定升级默认情况下是启用还是禁用。默认值为 true。这可以在路由级别使用 cluster 覆盖，如升级文档中所述。

extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.ProxyStatusConfig

[extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.ProxyStatusConfig proto]

配置填充 Proxy-Status HTTP 响应标头的方式。

请参阅 [Proxy-Status RFC](https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-proxy-status-08).

Proxy-Status 标头是一个字符串，格式为

“<server_name>; error=<error_type>; details=<details>”

{
  "remove_details": ...,
  "remove_connection_termination_details": ...,
  "remove_response_flags": ...,
  "set_recommended_response_code": ...,
  "use_node_id": ...,
  "literal_proxy_name": ...
}

remove_details: (布尔值) 如果为真，则 Proxy-Status 标头的 details 字段不会用 stream_info.response_code_details 填充。此值默认为 false，即默认情况下填充 details 字段。

remove_connection_termination_details: (布尔值) 如果为真，则 Proxy-Status 标头的 details 字段将不包含连接终止详细信息。此值默认为 false，即默认情况下 details 字段将包含连接终止详细信息。

remove_response_flags: (布尔值) 如果为真，则 Proxy-Status 标头的 details 字段将不包含 Envoy ResponseFlags 的枚举。此值默认为 false，即默认情况下 details 字段将包含 ResponseFlags 列表。

set_recommended_response_code: (布尔值) 如果为真，则将使用 Proxy-Status 规范推荐的响应代码覆盖现有的 Status 标头。此值默认为 false，即 HTTP 响应代码不会被覆盖。

use_node_id

(布尔值) 如果 use_node_id 已设置，则 Proxy-Status 标头将使用 Envoy 的节点 ID 作为代理的名称。

作为代理名称出现在 Proxy-Status 标头开头的名称。

如果这两个值都未设置，则此值默认为 server_name，其本身默认为“envoy”。

最多只能设置以下选项之一：use_node_id，literal_proxy_name。

literal_proxy_name

(string) 如果设置了literal_proxy_name，Proxy-Status 头部将使用此值作为代理的名称。

作为代理名称出现在 Proxy-Status 标头开头的名称。

如果这两个值都未设置，则此值默认为 server_name，其本身默认为“envoy”。

最多只能设置以下选项之一：use_node_id，literal_proxy_name。

extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.HcmAccessLogOptions

[extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.HcmAccessLogOptions proto]

{
  "access_log_flush_interval": {...},
  "flush_access_log_on_new_request": ...,
  "flush_log_on_tunnel_successfully_established": ...
}

access_log_flush_interval: (Duration) 用于刷新上述访问日志的间隔。默认情况下，HCM 将在流关闭时（HTTP 请求完成时）准确地刷新一个访问日志。如果设置了此字段，HCM 将以指定的间隔定期刷新访问日志。这在处理长生命周期请求（如 CONNECT 和 Websockets）时尤其有用。可以通过访问日志过滤器中的requestComplete() 方法或通过%DURATION% 替换字符串来检测最终访问日志。间隔必须至少为 1 毫秒。

flush_access_log_on_new_request: (bool) 如果设置为 true，HCM 将在接收到新的 HTTP 请求时刷新访问日志，在评估请求头部之后，在遍历 HTTP 过滤器链之前。如果启用此日志记录，该日志记录将不依赖于周期性日志记录或请求完成日志。与上游集群相关的详细信息（例如上游主机）将在此日志中不可用。

flush_log_on_tunnel_successfully_established: (bool) 如果为 true，当隧道建立成功时，HCM 将刷新访问日志。例如，这可能是当上游成功返回 101 Switching Protocols 时，或当代理对 CONNECT 请求返回 200 时。

Enum extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.CodecType

[extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.CodecType proto]

AUTO: (DEFAULT) ⁣对于每个新连接，连接管理器将确定要使用哪个编解码器。此模式支持 TLS 监听器上的 ALPN 以及明文监听器上的协议推断。如果有 ALPN 数据可用，则优先使用 ALPN 数据，否则使用协议推断。在几乎所有情况下，这都是此设置的正确选项。

HTTP1: ⁣连接管理器将假设客户端正在使用 HTTP/1.1。

HTTP2: ⁣连接管理器将假设客户端正在使用 HTTP/2（Envoy 不需要 HTTP/2 在 TLS 上运行或使用 ALPN。允许事先知道）。

HTTP3: ⁣连接管理器将假设客户端正在使用 HTTP/3。这需要与监听器和传输套接字配置保持一致。

Enum extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.ServerHeaderTransformation

[extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.ServerHeaderTransformation proto]

OVERWRITE: (DEFAULT) ⁣用 server_name 的内容覆盖任何 Server 头部。

APPEND_IF_ABSENT: ⁣如果不存在 Server 头部，则追加 Server server_name。如果存在 Server 头部，则将其传递。

PASS_THROUGH: ⁣传递 server 头部的值，如果不存在则不追加头部。

Enum extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.ForwardClientCertDetails

[extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.ForwardClientCertDetails proto]

如何处理x-forwarded-client-cert (XFCC) HTTP 头部。

SANITIZE: (DEFAULT) ⁣不要将 XFCC 头部发送到下一个跳跃点。这是默认值。

FORWARD_ONLY: ⁣当客户端连接为 mTLS（双向 TLS）时，在请求中转发 XFCC 头部。

APPEND_FORWARD: ⁣当客户端连接为 mTLS 时，将客户端证书信息追加到请求的 XFCC 头部并转发它。

SANITIZE_SET: ⁣当客户端连接为 mTLS 时，使用客户端证书信息重置 XFCC 头部并将其发送到下一个跳跃点。

ALWAYS_FORWARD_ONLY: ⁣始终在请求中转发 XFCC 头部，无论客户端连接是否为 mTLS。

Enum extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.PathWithEscapedSlashesAction

[extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.PathWithEscapedSlashesAction proto]

确定对 URI 路径中包含 %2F、%2f、%5C 或 %5c 序列的请求的操作。此操作在 URL 规范化和合并斜杠转换（如果启用）之前进行。

IMPLEMENTATION_SPECIFIC_DEFAULT: (DEFAULT) ⁣此配置选项的实现（即 Envoy）的默认行为。Envoy 默认情况下采用 KEEP_UNCHANGED 操作。注意：实现可能会随时更改默认行为。

KEEP_UNCHANGED: ⁣保留转义的斜杠。

REJECT_REQUEST: ⁣使用 400 状态拒绝客户端请求。gRPC 请求将使用 INTERNAL (13) 错误代码被拒绝。对于每个被拒绝的请求，都会增加“httpN.downstream_rq_failed_path_normalization”计数器。

UNESCAPE_AND_REDIRECT: ⁣取消转义 %2F 和 %5C 序列，如果存在这些序列，则将请求重定向到新路径。重定向在路径规范化和合并斜杠转换（如果配置）之后进行。注意：gRPC 请求将使用 INTERNAL (13) 错误代码被拒绝。此选项通过强制使用未转义斜杠的请求遍历所有方（下游客户端、中间代理、Envoy 和上游服务器）来最大限度地减少路径混淆攻击的可能性。“httpN.downstream_rq_redirected_with_normalized_path”计数器会为每个重定向的请求增加。

UNESCAPE_AND_FORWARD: ⁣取消转义 %2F 和 %5C 序列。注意：如果中间人执行基于路径的访问控制，则不应启用此选项，因为它可能导致路径混淆漏洞。

extensions.filters.network.http_connection_manager.v3.LocalReplyConfig

[extensions.filters.network.http_connection_manager.v3.LocalReplyConfig proto]

用于自定义 Envoy 返回的本地回复的配置。

{
  "mappers": [],
  "body_format": {...}
}

mappers: (repeated extensions.filters.network.http_connection_manager.v3.ResponseMapper) 用于过滤和更改本地回复的映射器列表配置。将按指定顺序检查映射器，直到匹配到一个映射器。

body_format

(config.core.v3.SubstitutionFormatString) 用于从命令操作符形成回复主体，并将回复内容类型指定为以下之一：plain/text 或 application/json。

示例一：“plain/text” body_format。

text_format: "%LOCAL_REPLY_BODY%:%RESPONSE_CODE%:path=%REQ(:path)%\n"

对于本地回复主体为“upstream connection error”，response_code=503 且路径为/foo 的请求，将生成以下“plain/text” 格式的回复主体。

upstream connect error:503:path=/foo

示例二：“application/json” body_format。

json_format:
  status: "%RESPONSE_CODE%"
  message: "%LOCAL_REPLY_BODY%"
  path: "%REQ(:path)%"

对于本地回复主体为“upstream connection error”，response_code=503 且路径为/foo 的请求，将生成以下“application/json” 格式的回复主体。

{
  "status": 503,
  "message": "upstream connection error",
  "path": "/foo"
}

extensions.filters.network.http_connection_manager.v3.ResponseMapper

[extensions.filters.network.http_connection_manager.v3.ResponseMapper proto]

用于过滤和更改本地回复的配置。

{
  "filter": {...},
  "status_code": {...},
  "body": {...},
  "body_format_override": {...},
  "headers_to_add": []
}

filter: (config.accesslog.v3.AccessLogFilter, REQUIRED) 用于确定是否应应用此映射器的过滤器。

status_code: (UInt32Value) 如果指定，则为新的回复状态代码。

body: (config.core.v3.DataSource) 如果指定，则为新的本地回复主体文本。它将在body_format 中的%LOCAL_REPLY_BODY% 命令操作符中使用。

body_format_override: (config.core.v3.SubstitutionFormatString) 用于覆盖body_format 的每个映射器 body_format。当此映射器匹配时将使用它。

headers_to_add: (repeated config.core.v3.HeaderValueOption) 要添加到本地回复的 HTTP 头部。这允许响应映射器在将本地回复发送到下游客户端之前，追加、添加或覆盖任何本地回复的头部。

extensions.filters.network.http_connection_manager.v3.Rds

[extensions.filters.network.http_connection_manager.v3.Rds proto]

{
  "config_source": {...},
  "route_config_name": ...
}

config_source: (config.core.v3.ConfigSource, REQUIRED) RDS 的配置源说明符。

route_config_name: (string) 路由配置的名称。此名称将传递给 RDS API。这允许具有多个 HTTP 监听器（以及关联的 HTTP 连接管理器过滤器）的 Envoy 配置使用不同的路由配置。

extensions.filters.network.http_connection_manager.v3.ScopedRouteConfigurationsList

[extensions.filters.network.http_connection_manager.v3.ScopedRouteConfigurationsList proto]

此消息用于解决“oneof”和重复字段的限制。

{
  "scoped_route_configurations": []
}

scoped_route_configurations: (repeated config.route.v3.ScopedRouteConfiguration, REQUIRED)

extensions.filters.network.http_connection_manager.v3.ScopedRoutes

[extensions.filters.network.http_connection_manager.v3.ScopedRoutes proto]

{
  "name": ...,
  "scope_key_builder": {...},
  "rds_config_source": {...},
  "scoped_route_configurations_list": {...},
  "scoped_rds": {...}
}

name: (string, REQUIRED) 分配给作用域路由配置的名称。

scope_key_builder: (extensions.filters.network.http_connection_manager.v3.ScopedRoutes.ScopeKeyBuilder, 必需) 用于为每个请求构建范围键的算法。

rds_config_source: (config.core.v3.ConfigSource) RDS 的配置源指定器。此配置源用于订阅在 ScopedRouteConfiguration 消息中指定的 RouteConfiguration 资源。

scoped_route_configurations_list

(extensions.filters.network.http_connection_manager.v3.ScopedRouteConfigurationsList) 与 HCM 对应的路由范围集。通过根据此消息中ScopeKeyBuilder中指定的算法，从请求的属性构建的键匹配范围，为请求分配范围。

必须设置scoped_route_configurations_list或scoped_rds中的一个。

scoped_rds

(extensions.filters.network.http_connection_manager.v3.ScopedRds) 与 HCM 关联的路由范围集将通过 SRDS API 动态加载。通过根据此消息中ScopeKeyBuilder中指定的算法，从请求的属性构建的键匹配范围，为请求分配范围。

必须设置scoped_route_configurations_list或scoped_rds中的一个。

extensions.filters.network.http_connection_manager.v3.ScopedRoutes.ScopeKeyBuilder

[extensions.filters.network.http_connection_manager.v3.ScopedRoutes.ScopeKeyBuilder proto]

指定基于 HTTP 请求属性构建“范围键”的机制。这些键与从通过 SRDS（范围路由发现服务）分发的ScopedRouteConfiguration消息中组装的Key对象集或通过scoped_route_configurations_list静态分配的一组对象进行匹配。

在接收到请求的标头后，路由器将使用此消息中指定的算法构建一个键。此键将用于查找要用于请求的路由表（即RouteConfiguration）。

{
  "fragments": []
}

fragments: (重复 extensions.filters.network.http_connection_manager.v3.ScopedRoutes.ScopeKeyBuilder.FragmentBuilder, 必需) 最终（构建）的范围键包含这些片段的有序并集，这些片段按顺序与ScopedRouteConfiguration的片段进行比较。比较期间缺少的片段将使键无效，即计算出的键与任何键都不匹配。

extensions.filters.network.http_connection_manager.v3.ScopedRoutes.ScopeKeyBuilder.FragmentBuilder

[extensions.filters.network.http_connection_manager.v3.ScopedRoutes.ScopeKeyBuilder.FragmentBuilder proto]

指定用于构建组成范围键的键片段的机制。

{
  "header_value_extractor": {...}
}

header_value_extractor: (extensions.filters.network.http_connection_manager.v3.ScopedRoutes.ScopeKeyBuilder.FragmentBuilder.HeaderValueExtractor, 必需) 指定如何提取标头字段的值。

extensions.filters.network.http_connection_manager.v3.ScopedRoutes.ScopeKeyBuilder.FragmentBuilder.HeaderValueExtractor

[extensions.filters.network.http_connection_manager.v3.ScopedRoutes.ScopeKeyBuilder.FragmentBuilder.HeaderValueExtractor proto]

指定如何提取标头的值。以下示例将标头的结构映射到此消息中的字段。

          <0> <1>   <-- index
X-Header: a=b;c=d
|         || |
|         || \----> <element_separator>
|         ||
|         |\----> <element.separator>
|         |
|         \----> <element.key>
|
\----> <name>

Each 'a=b' key-value pair constitutes an 'element' of the header field.

{
  "name": ...,
  "element_separator": ...,
  "index": ...,
  "element": {...}
}

name: (string, 必需) 要从中提取值的标头字段的名称。

注意

如果标头出现多次，则仅使用第一个值。

element_separator: (string) 元素分隔符（例如，‘;’ 分隔 ‘a;b;c;d’）。默认值：空字符串。这会导致提取标头字段的全部内容。如果此字段设置为空字符串并且在下面的 oneof 中使用 ‘index’，则 ‘index’ 必须设置为 0。

index

(uint32) 指定要提取的元素的从零开始的索引。注意，Envoy 将相同标头键的多个值连接成一个逗号分隔的字符串，分隔始终在连接之后发生。

只能设置index或element中的一个。

element

(extensions.filters.network.http_connection_manager.v3.ScopedRoutes.ScopeKeyBuilder.FragmentBuilder.HeaderValueExtractor.KvElement) 指定要从中提取值的键值对。

只能设置index或element中的一个。

extensions.filters.network.http_connection_manager.v3.ScopedRoutes.ScopeKeyBuilder.FragmentBuilder.HeaderValueExtractor.KvElement

[extensions.filters.network.http_connection_manager.v3.ScopedRoutes.ScopeKeyBuilder.FragmentBuilder.HeaderValueExtractor.KvElement proto]

指定要匹配的标头字段的键值对。

{
  "separator": ...,
  "key": ...
}

separator: (string, 必需) 键和值之间的分隔符（例如，‘=’ 分隔 ‘k=v;…’）。如果元素为空字符串，则忽略该元素。如果元素不包含任何分隔符，则整个元素将被解析为键，而片段值为一个空字符串。如果匹配的键有多个值，则返回第一个值。

key: (string, 必需) 要匹配的键。

extensions.filters.network.http_connection_manager.v3.ScopedRds

[extensions.filters.network.http_connection_manager.v3.ScopedRds proto]

{
  "scoped_rds_config_source": {...}
}

scoped_rds_config_source: (config.core.v3.ConfigSource, 必需) 范围 RDS 的配置源指定器。

extensions.filters.network.http_connection_manager.v3.HttpFilter

[extensions.filters.network.http_connection_manager.v3.HttpFilter proto]

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

name: (string, 必需) 过滤器配置的名称。它也充当 ExtensionConfigDS 中的资源名称。

typed_config

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

要支持配置匹配树，请使用带有所需 HTTP 过滤器的ExtensionWithMatcher。

提示

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

以下扩展仅在contrib镜像中可用

只能设置typed_config或config_discovery中的一个。

config_discovery

(config.core.v3.ExtensionConfigSource) 扩展配置发现服务的配置源指定器。在出现故障并且没有默认配置的情况下，HTTP 侦听器将以代码 500 响应。通过这种机制传递的扩展配置预计不需要预热（请参阅https://github.com/envoyproxy/envoy/issues/12061）。

要支持配置匹配树，请使用带有所需 HTTP 过滤器的ExtensionWithMatcher。这适用于默认过滤器配置以及通过 API 提供的过滤器。

只能设置typed_config或config_discovery中的一个。

is_optional: (bool) 如果为真，则不支持此过滤器的客户端可以忽略此过滤器，但否则接受配置。否则，不支持此过滤器的客户端必须拒绝配置。

disabled

(bool) 如果为真，则该过滤器默认情况下处于禁用状态，并且必须通过在路由配置中设置每个过滤器配置来显式启用。有关更多详细信息，请参阅基于路由的过滤器链。

终端过滤器（例如 envoy.filters.http.router）无法标记为禁用。

extensions.filters.network.http_connection_manager.v3.RequestIDExtension

[extensions.filters.network.http_connection_manager.v3.RequestIDExtension proto]

{
  "typed_config": {...}
}

typed_config: (Any) 请求 ID 扩展的特定配置。

extensions.filters.network.http_connection_manager.v3.EnvoyMobileHttpConnectionManager

[extensions.filters.network.http_connection_manager.v3.EnvoyMobileHttpConnectionManager proto]

用于 Envoy Mobile 的 HTTP 连接管理器。

此扩展的限定名称为 envoy.filters.network.envoy_mobile_http_connection_manager

注意

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

提示

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

envoy.filters.network

{
  "config": {...}
}

config: (extensions.filters.network.http_connection_manager.v3.HttpConnectionManager) 为 Envoy Mobile 实例化的底层 HttpConnectionManager 的配置。