HTTP 路由组件 (proto)

路由架构概述
HTTP 路由过滤器

config.route.v3.VirtualHost

路由配置中的顶级元素是虚拟主机。每个虚拟主机都有一个逻辑名称，以及一组根据传入请求的主机头路由到它的域名。这允许单个监听器为多个顶级域名路径树提供服务。一旦根据域名选择了虚拟主机，就会按顺序处理路由，以查看要路由到的上游集群或是否执行重定向。

{
  "name": ...,
  "domains": [],
  "routes": [],
  "matcher": {...},
  "require_tls": ...,
  "virtual_clusters": [],
  "rate_limits": [],
  "request_headers_to_add": [],
  "request_headers_to_remove": [],
  "response_headers_to_add": [],
  "response_headers_to_remove": [],
  "cors": {...},
  "typed_per_filter_config": {...},
  "include_request_attempt_count": ...,
  "include_attempt_count_in_response": ...,
  "retry_policy": {...},
  "hedge_policy": {...},
  "include_is_timeout_retry_header": ...,
  "per_request_buffer_limit_bytes": {...},
  "request_mirror_policies": [],
  "metadata": {...}
}

名称: (string, REQUIRED) 虚拟主机的逻辑名称。这在发出某些统计数据时使用，但与路由无关。

域名

(repeated string, REQUIRED) 将与该虚拟主机匹配的域名（主机/授权标头）列表。支持后缀或前缀形式的通配符主机。

域名搜索顺序

确切的域名： www.foo.com。
后缀域名通配符： *.foo.com 或 *-bar.foo.com。
前缀域名通配符： foo.* 或 foo-*。
特殊通配符 * 匹配任何域名。

注意

通配符不会匹配空字符串。例如 *-bar.foo.com 将匹配 baz-bar.foo.com 但不匹配 -bar.foo.com。最长的通配符优先匹配。整个路由配置中只有一个虚拟主机可以匹配 *。域名必须在所有虚拟主机中唯一，否则配置将无法加载。

域名不能包含控制字符。这由 well_known_regex HTTP_HEADER_VALUE 验证。

路由: (repeated config.route.v3.Route) 将匹配的路由列表，按顺序，用于传入请求。第一个匹配的路由将被使用。只能指定此选项或 matcher。

匹配器: (.xds.type.matcher.v3.Matcher) 用于解析传入请求的路由操作的匹配树。只能指定此选项或 routes。

require_tls: (config.route.v3.VirtualHost.TlsRequirementType) 指定虚拟主机期望的 TLS 强制类型。如果未指定此选项，则虚拟主机没有 TLS 要求。

虚拟集群: (repeated config.route.v3.VirtualCluster) 为该虚拟主机定义的虚拟集群列表。虚拟集群用于收集其他统计数据。

速率限制: (repeated config.route.v3.RateLimit) 指定将应用于虚拟主机的一组速率限制配置。

要添加的请求头: (repeated config.core.v3.HeaderValueOption) 指定应添加到此虚拟主机处理的每个请求的 HTTP 标头列表。在此级别指定的标头在来自封闭 config.route.v3.Route 的标头之后应用，在来自封闭 config.route.v3.RouteConfiguration 的标头之前应用。有关更多信息，包括有关标头值语法的详细信息，请参阅有关自定义请求标头的文档。

要删除的请求头: (repeated string) 指定应从此虚拟主机处理的每个请求中删除的 HTTP 标头列表。

要添加的响应头: (repeated config.core.v3.HeaderValueOption) 指定应添加到此虚拟主机处理的每个响应的 HTTP 标头列表。在此级别指定的标头在来自封闭 config.route.v3.Route 的标头之后应用，在来自封闭 config.route.v3.RouteConfiguration 的标头之前应用。有关更多信息，包括有关标头值语法的详细信息，请参阅有关自定义请求标头的文档。

要删除的响应头: (repeated string) 指定应从此虚拟主机处理的每个响应中删除的 HTTP 标头列表。

CORS: (config.route.v3.CorsPolicy) 表示虚拟主机具有 CORS 策略。如果在 VirtualHost.typed_per_filter_config 中找到了相关 CORS 策略，则忽略此字段。

注意

此选项已弃用。请使用 VirtualHost.typed_per_filter_config 来配置 CORS HTTP 过滤器。

typed_per_filter_config: (repeated map<string, Any>) 此字段可用于提供虚拟主机级别的每个过滤器配置。密钥应与过滤器配置名称匹配。有关详细信息，请参阅 HTTP 过滤器路由特定配置。

include_request_attempt_count: (bool) 决定是否应将 x-envoy-attempt-count 标头包含在上游请求中。设置此选项将导致它覆盖任何现有的标头值，因此，如果请求路径上有两个 Envoy 启用了此选项，上游将看到第二个 Envoy 感知的尝试次数。默认为 false。此标头不受 suppress_envoy_headers 标志的影响。

include_attempt_count_in_response: (bool) 决定是否应将 x-envoy-attempt-count 标头包含在下游响应中。设置此选项将导致路由器覆盖任何现有的标头值，因此，如果请求路径上有两个 Envoy 启用了此选项，下游将看到与自身最接近的上游 Envoy 感知的尝试次数。默认为 false。此标头不受 suppress_envoy_headers 标志的影响。

重试策略: (config.route.v3.RetryPolicy) 指示此虚拟主机中所有路由的重试策略。请注意，设置路由级别条目将优先于此配置，并且将独立处理（例如：值不会继承）。

对冲策略: (config.route.v3.HedgePolicy) 指示此虚拟主机中所有路由的对冲策略。请注意，设置路由级别条目将优先于此配置，并且将独立处理（例如：值不会继承）。

include_is_timeout_retry_header: (bool) 决定是否在每次尝试超时启动的重试中包含 x-envoy-is-timeout-retry 请求标头。

per_request_buffer_limit_bytes: (UInt32Value) 将为重试和影子缓冲的字节的最大值。如果设置且未设置路由特定的限制，则实际缓冲的字节将是此值和监听器 per_connection_buffer_limit_bytes 的最小值。

request_mirror_policies: (repeated config.route.v3.RouteAction.RequestMirrorPolicy) 为此虚拟主机下的每个路由指定一组默认请求镜像策略。它完全优先于路由配置镜像策略。也就是说，策略不会合并，最具体的非空策略将成为镜像策略。

元数据: (config.core.v3.Metadata) 元数据字段可用于提供有关虚拟主机的其他信息。它可用于配置、统计和日志记录。元数据应位于需要它的过滤器命名空间下。例如，如果元数据是为 Router 过滤器准备的，则过滤器名称应指定为 envoy.filters.http.router。

枚举 config.route.v3.VirtualHost.TlsRequirementType

[config.route.v3.VirtualHost.TlsRequirementType proto]

NONE: (默认) ⁣虚拟主机没有 TLS 要求。

EXTERNAL_ONLY: ⁣外部请求必须使用 TLS。如果请求是外部请求，并且没有使用 TLS，则会发送 301 重定向，告知客户端使用 HTTPS。

ALL: ⁣所有请求必须使用 TLS。如果请求没有使用 TLS，则会发送 301 重定向，告知客户端使用 HTTPS。

config.route.v3.FilterAction

[config.route.v3.FilterAction proto]

过滤器定义的动作类型。

{
  "action": {...}
}

action: (Any)

config.route.v3.RouteList

[config.route.v3.RouteList proto]

这可以在路由匹配器 VirtualHost.matcher 中使用。当匹配器匹配时，将匹配并运行路由。

{
  "routes": []
}

路由: (repeated config.route.v3.Route) 将匹配并运行的路由列表，按顺序排列。将使用第一个匹配的路由。

config.route.v3.Route

[config.route.v3.Route proto]

路由既指定了如何匹配请求，也指示了下一步要做什么（例如，重定向、转发、重写等）。

注意

Envoy 支持通过标头匹配对 HTTP 方法进行路由。

{
  "name": ...,
  "match": {...},
  "route": {...},
  "redirect": {...},
  "direct_response": {...},
  "metadata": {...},
  "decorator": {...},
  "typed_per_filter_config": {...},
  "request_headers_to_add": [],
  "request_headers_to_remove": [],
  "response_headers_to_add": [],
  "response_headers_to_remove": [],
  "tracing": {...},
  "per_request_buffer_limit_bytes": {...},
  "stat_prefix": ...
}

名称: (string) 路由的名称。

match: (config.route.v3.RouteMatch, 必需) 路由匹配参数。

route

(config.route.v3.RouteAction) 将请求路由到某个上游集群。

必须恰好设置一个 route、redirect、direct_response。

redirect

(config.route.v3.RedirectAction) 返回重定向。

必须恰好设置一个 route、redirect、direct_response。

direct_response

(config.route.v3.DirectResponseAction) 直接返回任意 HTTP 响应，无需代理。

必须恰好设置一个 route、redirect、direct_response。

元数据: (config.core.v3.Metadata) 元数据字段可用于提供有关路由的额外信息。它可用于配置、统计和日志记录。元数据应位于需要它的过滤器命名空间下。例如，如果元数据是为 Router 过滤器准备的，则过滤器名称应指定为 envoy.filters.http.router。

decorator: (config.route.v3.Decorator) 匹配路由的修饰器。

typed_per_filter_config: (repeated map<string, Any>) 此字段可用于提供针对特定路由的每个过滤器配置。键应与过滤器配置名称匹配。有关详细信息，请参阅 Http 过滤器路由特定配置。

要添加的请求头: (repeated config.core.v3.HeaderValueOption) 指定将添加到与该路由匹配的请求的一组标头。在此级别指定的标头在来自封闭 config.route.v3.VirtualHost 和 config.route.v3.RouteConfiguration 的标头之前应用。有关更多信息，包括有关标头值语法的详细信息，请参阅自定义请求标头的文档。

要删除的请求头: (repeated string) 指定应从与该路由匹配的每个请求中删除的 HTTP 标头列表。

要添加的响应头: (repeated config.core.v3.HeaderValueOption) 指定将添加到对与该路由匹配的请求的响应的一组标头。在此级别指定的标头在来自封闭 config.route.v3.VirtualHost 和 config.route.v3.RouteConfiguration 的标头之前应用。有关更多信息，包括有关标头值语法的详细信息，请参阅自定义请求标头的文档。

要删除的响应头: (repeated string) 指定应从对与该路由匹配的每个请求的响应中删除的 HTTP 标头列表。

tracing: (config.route.v3.Tracing) 对象的存在定义了连接管理器的跟踪配置是否被该路由特定的实例覆盖。

per_request_buffer_limit_bytes: (UInt32Value) 将为重试和影子缓冲的最大字节数。如果设置，实际缓冲的字节数将是此值和侦听器 per_connection_buffer_limit_bytes 的最小值。

stat_prefix

(string) 为此端点发出统计信息时使用的可读前缀。统计信息以 vhost.<虚拟主机名称>.route.<stat_prefix> 为根。这应该为希望获得“每路由”统计信息的非常重要的端点设置。如果未设置，则不会生成端点统计信息。

发出的统计信息与为虚拟集群文档化的统计信息相同。

警告

我们不建议为每个应用程序端点设置 stat 前缀。这既不容易维护，而且统计信息会使用相当数量的内存（大约每路由 1KiB）。

config.route.v3.WeightedCluster

[config.route.v3.WeightedCluster proto]

与 cluster 字段指定单个上游集群作为请求的目标相比，weighted_clusters 选项允许指定多个上游集群以及表示转发到每个集群的流量百分比的权重。路由器根据权重选择上游集群。

{
  "clusters": [],
  "total_weight": {...},
  "runtime_key_prefix": ...,
  "header_name": ...
}

clusters: (repeated config.route.v3.WeightedCluster.ClusterWeight, 必需) 指定与路由关联的一个或多个上游集群。

total_weight: (UInt32Value) 指定所有集群的总权重。如果此值大于 0，则所有集群权重的总和必须等于此值。此字段现已弃用，客户端将使用所有集群权重的总和。管理服务器负责提供正确的权重。

runtime_key_prefix: (string) 指定用于构建与每个集群关联的运行时键的运行时键前缀。当指定 runtime_key_prefix 时，路由器将在键 runtime_key_prefix + . + cluster[i].name 下查找与每个上游集群关联的权重，其中 cluster[i] 表示集群数组字段中的一个条目。如果集群的运行时键不存在，则配置文件中指定的值将用作默认权重。有关键名如何映射到底层实现的详细信息，请参阅运行时文档。

header_name: (string) 指定用于查找请求标头中传入的随机值的标头名称。这用于确保在多个代理级别进行加权流量时，始终选择相同的集群。如果标头不存在或无效，Envoy 将回退使用内部生成的随机值。此标头预计是单值标头，因为我们只希望在整个过程中有一个选定的值，以确保一致性。并且该值是一个介于 0 到 UINT64_MAX 之间的无符号数字。

config.route.v3.WeightedCluster.ClusterWeight

[config.route.v3.WeightedCluster.ClusterWeight proto]

{
  "name": ...,
  "cluster_header": ...,
  "weight": {...},
  "metadata_match": {...},
  "request_headers_to_add": [],
  "request_headers_to_remove": [],
  "response_headers_to_add": [],
  "response_headers_to_remove": [],
  "typed_per_filter_config": {...},
  "host_rewrite_literal": ...
}

名称: (string) 只能指定 name 或 cluster_header 之一。上游集群的名称。该集群必须存在于集群管理器配置中。

cluster_header: (string) 只能指定 name 或 cluster_header 之一。Envoy 将通过读取请求标头中名为 cluster_header 的 HTTP 标头的值来确定要路由到的集群。如果未找到标头或引用的集群不存在，Envoy 将返回 404 响应。

注意

在内部，Envoy 始终使用 HTTP/2 的 :authority 头部来表示 HTTP/1 的 Host 头部。因此，如果尝试匹配 Host，请改用 :authority 进行匹配。

注意

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

权重: (UInt32Value) 集群的权重。此值相对于其他集群的权重。当请求匹配路由时，上游集群的选择将由其权重决定。集群数组中所有条目的权重之和必须大于 0，并且不得超过 uint32_t 的最大值 (4294967295)。

元数据匹配: (config.core.v3.Metadata) 子集负载均衡器使用的可选端点元数据匹配条件。仅上游集群中元数据与此字段中设置的元数据匹配的端点将被视为负载均衡的目标。请注意，这将与 RouteAction.metadata_match 中提供的元数据合并，此处的值优先。过滤器名称应指定为 envoy.lb。

要添加的请求头: (repeated config.core.v3.HeaderValueOption) 指定当通过封闭的 config.route.v3.RouteAction 选择此集群时，要添加到请求中的头部列表。在此级别上指定的头部将在来自封闭的 config.route.v3.Route、config.route.v3.VirtualHost 和 config.route.v3.RouteConfiguration 的头部之前应用。有关更多信息，包括有关头部值语法的详细信息，请参阅有关自定义请求头部的文档。

要删除的请求头: (repeated string) 指定当通过封闭的 config.route.v3.RouteAction 选择此集群时，应从每个请求中删除的 HTTP 头部列表。

要添加的响应头: (repeated config.core.v3.HeaderValueOption) 指定当通过封闭的 config.route.v3.RouteAction 选择此集群时，要添加到响应中的头部列表。在此级别上指定的头部将在来自封闭的 config.route.v3.Route、config.route.v3.VirtualHost 和 config.route.v3.RouteConfiguration 的头部之前应用。有关更多信息，包括有关头部值语法的详细信息，请参阅有关自定义请求头部的文档。

要删除的响应头: (repeated string) 指定当通过封闭的 config.route.v3.RouteAction 选择此集群时，应从响应中删除的头部列表。

typed_per_filter_config: (repeated map<string, Any>) 此字段可用于提供加权集群特定每个过滤器的配置。键应与过滤器配置名称匹配。有关详细信息，请参阅 Http 过滤器路由特定配置。

主机重写字面量: (string) 指示在转发期间，主机头部将被此值替换。

config.route.v3.ClusterSpecifierPlugin

[config.route.v3.ClusterSpecifierPlugin proto]

集群指定器插件的配置。

{
  "extension": {...},
  "is_optional": ...
}

扩展: (config.core.v3.TypedExtensionConfig, REQUIRED) 插件的名称及其不透明配置。

是否可选: (bool) 如果 is_optional 未设置或设置为 false，并且此消息定义的插件不是支持的类型，则包含的资源将被 NACK。如果 is_optional 设置为 true，则资源不会因此原因而被 NACK。在这种情况下，引用此插件名称的路由不会被视为非法配置，但如果选择该路由，将导致失败。

config.route.v3.RouteMatch

[config.route.v3.RouteMatch proto]

{
  "prefix": ...,
  "path": ...,
  "safe_regex": {...},
  "connect_matcher": {...},
  "path_separated_prefix": ...,
  "path_match_policy": {...},
  "case_sensitive": {...},
  "runtime_fraction": {...},
  "headers": [],
  "query_parameters": [],
  "grpc": {...},
  "tls_context": {...},
  "dynamic_metadata": []
}

前缀

(string) 如果指定，则路由是一个前缀规则，这意味着前缀必须与 :path 头部的开头匹配。

必须准确设置一个 prefix、path、safe_regex、connect_matcher、path_separated_prefix、path_match_policy。

路径

(string) 如果指定，则路由是一个精确路径规则，这意味着路径必须与 :path 头部完全匹配，前提是删除了查询字符串。

必须准确设置一个 prefix、path、safe_regex、connect_matcher、path_separated_prefix、path_match_policy。

安全正则表达式

(type.matcher.v3.RegexMatcher) 如果指定，则路由是一个正则表达式规则，这意味着正则表达式必须与 :path 头部匹配，前提是删除了查询字符串。整个路径（不包括查询字符串）必须与正则表达式匹配。如果 :path 头部的子序列与正则表达式匹配，则规则将不匹配。

必须准确设置一个 prefix、path、safe_regex、connect_matcher、path_separated_prefix、path_match_policy。

连接匹配器

(config.route.v3.RouteMatch.ConnectMatcher) 如果将其用作匹配器，则匹配器将仅匹配 CONNECT 或 CONNECT-UDP 请求。请注意，这将不匹配其他扩展 CONNECT 请求（WebSocket 等），因为它们在 Envoy 中被规范化为 HTTP/1.1 样式升级。这是匹配 HTTP/1.1 的 CONNECT 请求的唯一方法。对于 HTTP/2 和 HTTP/3，扩展 CONNECT 请求可能具有路径，如果存在路径，则路径匹配器将起作用。请注意，CONNECT 支持目前在 Envoy 中被视为 alpha 版。

必须准确设置一个 prefix、path、safe_regex、connect_matcher、path_separated_prefix、path_match_policy。

路径分隔前缀

(string) 如果指定，则路由是一个路径分隔前缀规则，这意味着 :path 头部（不包括查询字符串）必须与 path_separated_prefix 完全匹配，或者以其作为前缀，后跟 /

例如，/api/dev 将匹配 /api/dev、/api/dev/、/api/dev/v1 和 /api/dev?param=true，但不会匹配 /api/developer

预期值不包含 ? 或 #，并且不以 / 结尾

必须准确设置一个 prefix、path、safe_regex、connect_matcher、path_separated_prefix、path_match_policy。

路径匹配策略

(config.core.v3.TypedExtensionConfig)

提示

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

envoy.path.match.uri_template.uri_template_matcher

必须准确设置一个 prefix、path、safe_regex、connect_matcher、path_separated_prefix、path_match_policy。

区分大小写: (BoolValue) 指示前缀/路径匹配是否区分大小写。默认值为 true。忽略安全正则表达式匹配。

运行时分数: (config.core.v3.RuntimeFractionalPercent) 指示路由还应在运行时键上匹配。每次考虑路由进行匹配时，它也必须落在此字段指示的匹配百分比范围内。对于某个分数 N/D，会选择 [0,D) 范围内的随机数。如果该数字 <= 分子 N 的值，或者如果键不存在，则使用默认值，路由器将继续评估剩余的匹配条件。运行时分数路由配置可用于以逐步方式推出路由更改，而无需完全进行代码/配置部署。有关其他文档，请参阅流量转移文档。

注意

解析此字段的实现方式使得运行时键的数据可以表示为以 JSON/YAML 表示的 FractionalPercent proto，也可以表示为整数，假设该值为 100 中的整数百分比。例如，运行时键查找返回的值为“42”将解析为 FractionalPercent，其分子为 42，分母为 HUNDRED。这保留了旧的语义。

头部: (repeated config.route.v3.HeaderMatcher) 指定路由应匹配的一组头部。路由器将检查请求的头部与路由配置中指定的所有头部。如果路由中的所有头部都存在于请求中，并且具有相同的值（或者如果配置中没有 value 字段，则基于存在性），则匹配将发生。

查询参数: (重复 config.route.v3.QueryParameterMatcher) 指定路由应匹配的一组 URL 查询参数。路由器将检查 path 标头中的查询字符串与所有指定的查询参数。如果指定了非零数量的查询参数，则它们都必须与 path 标头的查询字符串匹配，才能发生匹配。如果查询参数重复，则只考虑每个键的第一个值。

注意

如果使用查询参数在使用 grpc_json_transcoder 时传递请求消息字段，则转码的消息字段可能不同。查询参数是 URL 编码的，但消息字段不是。例如，如果查询参数是“foo%20bar”，则消息字段将是“foo bar”。

grpc: (config.route.v3.RouteMatch.GrpcRouteMatchOptions) 如果指定，则只匹配 gRPC 请求。路由器将检查内容类型标头是否包含 application/grpc 或各种 application/grpc+ 值之一。

tls_context: (config.route.v3.RouteMatch.TlsContextMatchOptions) 如果指定，则客户端 tls 上下文将与定义的匹配选项进行匹配。

dynamic_metadata: (重复 type.matcher.v3.MetadataMatcher) 指定路由应匹配的一组动态元数据匹配器。路由器将检查动态元数据与所有指定的动态元数据匹配器。如果指定了非零数量的动态元数据匹配器，则它们都必须与动态元数据匹配，才能发生匹配。

config.route.v3.RouteMatch.GrpcRouteMatchOptions

[config.route.v3.RouteMatch.GrpcRouteMatchOptions proto]

config.route.v3.RouteMatch.TlsContextMatchOptions

[config.route.v3.RouteMatch.TlsContextMatchOptions proto]

{
  "presented": {...},
  "validated": {...}
}

presented: (BoolValue) 如果指定，则路由将匹配证书是否已呈现。如果未指定，则证书呈现状态（true 或 false）在路由匹配时不会被考虑。

validated: (BoolValue) 如果指定，则路由将匹配证书是否已验证。如果未指定，则证书验证状态（true 或 false）在路由匹配时不会被考虑。

警告

目前在 TLS 会话恢复时不会执行客户端证书验证。对于恢复的 TLS 会话，路由只会在 validated 为 false 时匹配，无论客户端 TLS 证书是否有效。

此问题的唯一已知解决方法是完全禁用 TLS 会话恢复，方法是在 DownstreamTlsContext 上同时设置 disable_stateless_session_resumption 和 disable_stateful_session_resumption。

config.route.v3.RouteMatch.ConnectMatcher

[config.route.v3.RouteMatch.ConnectMatcher proto]

用于匹配 CONNECT 或 CONNECT-UDP 请求的可扩展消息。

config.route.v3.CorsPolicy

[config.route.v3.CorsPolicy proto]

CORS 策略配置。

注意

此消息已弃用。请使用过滤器扩展中的 CorsPolicy 作为替代方案。

{
  "allow_origin_string_match": [],
  "allow_methods": ...,
  "allow_headers": ...,
  "expose_headers": ...,
  "max_age": ...,
  "allow_credentials": {...},
  "filter_enabled": {...},
  "shadow_enabled": {...},
  "allow_private_network_access": {...},
  "forward_not_matching_preflights": {...}
}

allow_origin_string_match: (重复 type.matcher.v3.StringMatcher) 指定与允许的来源匹配的字符串模式。如果任何字符串匹配器匹配，则来源是允许的。

allow_methods: (string) 指定 access-control-allow-methods 标头的内容。

allow_headers: (string) 指定 access-control-allow-headers 标头的内容。

expose_headers: (string) 指定 access-control-expose-headers 标头的内容。

max_age: (string) 指定 access-control-max-age 标头的内容。

allow_credentials: (BoolValue) 指定资源是否允许凭据。

filter_enabled

(config.core.v3.RuntimeFractionalPercent) 指定启用 CORS 过滤器的请求百分比。

如果未指定 enabled、filter_enabled 或 shadow_enabled，则 CORS 过滤器将对 100% 的请求启用。

如果指定了 runtime_key，则 Envoy 将查找运行时键以获取要过滤的请求百分比。

shadow_enabled

(config.core.v3.RuntimeFractionalPercent) 指定将评估和跟踪 CORS 策略但不会强制执行的请求百分比。

此字段旨在用于 filter_enabled 和 enabled 关闭时。为了使此设置生效，必须明确禁用其中一个字段。

如果指定了 runtime_key，则 Envoy 将查找运行时键以获取它将评估和跟踪请求的 Origin 以确定其是否有效，但不会强制执行任何策略。

allow_private_network_access

(BoolValue) 指定是否允许目标服务器的 IP 地址比请求发起者获取的 IP 地址更私有的请求。

更多详细信息请参考 https://developer.chrome.com/blog/private-network-access-preflight。

forward_not_matching_preflights: (BoolValue) 指定不匹配配置的允许来源的预检请求是否应转发到上游。默认值为 true。

config.route.v3.RouteAction

[config.route.v3.RouteAction proto]

{
  "cluster": ...,
  "cluster_header": ...,
  "weighted_clusters": {...},
  "cluster_specifier_plugin": ...,
  "inline_cluster_specifier_plugin": {...},
  "cluster_not_found_response_code": ...,
  "metadata_match": {...},
  "prefix_rewrite": ...,
  "regex_rewrite": {...},
  "path_rewrite_policy": {...},
  "host_rewrite_literal": ...,
  "auto_host_rewrite": {...},
  "host_rewrite_header": ...,
  "host_rewrite_path_regex": {...},
  "append_x_forwarded_host": ...,
  "timeout": {...},
  "idle_timeout": {...},
  "early_data_policy": {...},
  "retry_policy": {...},
  "request_mirror_policies": [],
  "priority": ...,
  "rate_limits": [],
  "include_vh_rate_limits": {...},
  "hash_policy": [],
  "cors": {...},
  "max_grpc_timeout": {...},
  "grpc_timeout_offset": {...},
  "upgrade_configs": [],
  "internal_redirect_policy": {...},
  "internal_redirect_action": ...,
  "max_internal_redirects": {...},
  "hedge_policy": {...},
  "max_stream_duration": {...}
}

cluster

(string) 指示应将请求路由到的上游集群。

必须设置 cluster、cluster_header、weighted_clusters、cluster_specifier_plugin、inline_cluster_specifier_plugin 中的其中一个。

cluster_header

(string) Envoy 将通过从请求标头中读取名为 cluster_header 的 HTTP 标头的值来确定要路由到的集群。如果未找到标头或引用的集群不存在，则 Envoy 将返回 404 响应。

注意

在内部，Envoy 始终使用 HTTP/2 的 :authority 头部来表示 HTTP/1 的 Host 头部。因此，如果尝试匹配 Host，请改用 :authority 进行匹配。

注意

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

必须设置 cluster、cluster_header、weighted_clusters、cluster_specifier_plugin、inline_cluster_specifier_plugin 中的其中一个。

weighted_clusters

(config.route.v3.WeightedCluster) 可以为给定路由指定多个上游集群。请求将根据分配给每个集群的权重路由到其中一个上游集群。有关更多文档，请参阅流量拆分。

必须设置 cluster、cluster_header、weighted_clusters、cluster_specifier_plugin、inline_cluster_specifier_plugin 中的其中一个。

cluster_specifier_plugin

(string) 要使用以确定此路由上请求的集群的集群指定器插件的名称。集群指定器插件名称必须在关联的集群指定器插件中的 name 字段中定义。

必须设置 cluster、cluster_header、weighted_clusters、cluster_specifier_plugin、inline_cluster_specifier_plugin 中的其中一个。

inline_cluster_specifier_plugin

(config.route.v3.ClusterSpecifierPlugin) 要使用以确定此路由上请求的集群的自定义集群指定器插件配置。

必须设置 cluster、cluster_header、weighted_clusters、cluster_specifier_plugin、inline_cluster_specifier_plugin 中的其中一个。

cluster_not_found_response_code: (config.route.v3.RouteAction.ClusterNotFoundResponseCode) 当配置的集群未找到时要使用的 HTTP 状态代码。默认响应代码为 503 服务不可用。

元数据匹配: (config.core.v3.Metadata) 子集负载均衡器使用的可选端点元数据匹配条件。上游集群中只有元数据与这里设置的内容匹配的端点才会被考虑进行负载均衡。如果使用 weighted_clusters，则元数据将被合并，其中提供的值优先。过滤器名称应指定为 envoy.lb。

prefix_rewrite

(string) 指示在转发期间，应将匹配的前缀（或路径）替换为此值。此选项允许应用程序 URL 的根目录与在反向代理层公开的根目录不同。路由器过滤器将把重写前的原始路径放在 x-envoy-original-path 标头中。

只能指定 regex_rewrite、path_rewrite_policy 或 prefix_rewrite 中的其中一个。

注意

请仔细注意路由匹配前缀值中尾部斜杠的使用。从路径中删除前缀需要多个路由来处理所有情况。例如，将 /prefix 重写为 / 以及 /prefix/etc 重写为 /etc 无法在一个路由中完成，如下面的配置项所示

- match:
    prefix: "/prefix/"
  route:
    prefix_rewrite: "/"
- match:
    prefix: "/prefix"
  route:
    prefix_rewrite: "/"

在配置中包含上面的项后，对 /prefix 的请求将被截断为 /，而对 /prefix/etc 的请求将被截断为 /etc。

regex_rewrite

(type.matcher.v3.RegexMatchAndSubstitute) 指示在转发过程中，应该重写与模式匹配的路径部分，甚至允许将模式中的捕获组替换到新的路径中，如重写替换字符串中所指定的那样。这对于允许以感知具有可变内容（如标识符）的段的方式重写应用程序路径非常有用。路由器过滤器会将原始路径（重写之前）放入 x-envoy-original-path 标头中。

只能指定 regex_rewrite、prefix_rewrite 或 path_rewrite_policy 中的其中一个。

使用 Google 的 RE2 引擎的示例

路径模式 ^/service/([^/]+)(/.*)$ 与替换字符串 \2/instance/\1 配对，将 /service/foo/v1/api 转换为 /v1/api/instance/foo。
模式 one 与替换字符串 two 配对，将 /xxx/one/yyy/one/zzz 转换为 /xxx/two/yyy/two/zzz。
模式 ^(.*?)one(.*)$ 与替换字符串 \1two\2 配对，将只替换 one 的第一个出现，将路径 /xxx/one/yyy/one/zzz 转换为 /xxx/two/yyy/one/zzz。
模式 (?i)/xxx/ 与替换字符串 /yyy/ 配对，将进行不区分大小写的匹配，并将路径 /aaa/XxX/bbb 转换为 /aaa/yyy/bbb。

path_rewrite_policy

(config.core.v3.TypedExtensionConfig)

提示

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

envoy.path.rewrite.uri_template.uri_template_rewriter

主机重写字面量

(string) 指示在转发过程中，主机头将被替换为该值。使用此选项将在 append_x_forwarded_host 设置的情况下追加 x-forwarded-host 标头。

只能设置 host_rewrite_literal、auto_host_rewrite、host_rewrite_header、host_rewrite_path_regex 中的其中一个。

auto_host_rewrite

(BoolValue) 指示在转发过程中，主机头将被替换为集群管理器选择的上游主机的 hostname。此选项仅适用于路由的目的地集群类型为 strict_dns 或 logical_dns，或 hostname 字段不为空的情况。对于其他集群类型，将其设置为 true 不会产生任何影响。使用此选项将在 append_x_forwarded_host 设置的情况下追加 x-forwarded-host 标头。

只能设置 host_rewrite_literal、auto_host_rewrite、host_rewrite_header、host_rewrite_path_regex 中的其中一个。

host_rewrite_header

(string) 指示在转发过程中，主机头将被替换为给定下游或自定义标头的内容。如果标头值为空，则主机头保持不变。使用此选项将在 append_x_forwarded_host 设置的情况下追加 x-forwarded-host 标头。

注意

请注意使用此选项的潜在安全隐患。提供的标头必须来自可信来源。

注意

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

只能设置 host_rewrite_literal、auto_host_rewrite、host_rewrite_header、host_rewrite_path_regex 中的其中一个。

host_rewrite_path_regex

(type.matcher.v3.RegexMatchAndSubstitute) 指示在转发过程中，主机头将被替换为在路径值（去掉查询和片段）上执行的正则表达式替换结果。这对于在路径段和子域之间转换可变内容很有用。使用此选项将在 append_x_forwarded_host 设置的情况下追加 x-forwarded-host 标头。

例如，使用以下配置

host_rewrite_path_regex:
  pattern:
    google_re2: {}
    regex: "^/(.+)/.+$"
  substitution: \1

将主机头重写为 envoyproxy.io，路径为 /envoyproxy.io/some/path。

只能设置 host_rewrite_literal、auto_host_rewrite、host_rewrite_header、host_rewrite_path_regex 中的其中一个。

append_x_forwarded_host: (bool) 如果设置，则主机重写操作（host_rewrite_literal、auto_host_rewrite、host_rewrite_header 或 host_rewrite_path_regex 中的其中一个）会导致原始主机头值（如果有）追加到 x-forwarded-host HTTP 标头中（如果它与上次追加的值不同）。

timeout: (Duration) 指定路由的上游超时时间。如果未指定，则默认值为 15 秒。这跨越了整个下游请求（即数据流结束）已处理的点到上游响应已完全处理的点之间的范围。值为 0 将禁用路由的超时时间。

注意

此超时时间包括所有重试。另请参阅 x-envoy-upstream-rq-timeout-ms、x-envoy-upstream-rq-per-try-timeout-ms 以及重试概述。

idle_timeout

(Duration) 指定路由的空闲超时时间。如果未指定，则没有每路由空闲超时时间，尽管连接管理器范围内的 stream_idle_timeout 仍然适用。值为 0 将完全禁用路由的空闲超时时间，即使配置了连接管理器的流空闲超时时间。

空闲超时时间与 timeout 不同，timeout 提供了上游响应时间的上限；idle_timeout 限制了请求数据流可能处于空闲状态的时间。

在标头解码后，空闲超时时间将应用于下游和上游请求事件。每次为数据流处理标头或数据的编码/解码事件时，计时器都会重置。如果超时时间到期，则如果未收到上游响应标头，则数据流将以 408 请求超时错误代码终止，否则将发生数据流重置。

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

early_data_policy

(config.core.v3.TypedExtensionConfig) 指定如何通过 TLS 早期数据发送请求。如果缺失，则允许将安全的 HTTP 请求发送到早期数据。

提示

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

envoy.route.early_data_policy.default

重试策略: (config.route.v3.RetryPolicy) 指示路由具有重试策略。请注意，如果设置了此策略，它将完全优先于虚拟主机级别的重试策略（例如：策略不会合并，最内部的策略将成为强制执行的策略）。

request_mirror_policies: (**重复** config.route.v3.RouteAction.RequestMirrorPolicy) 指定一组路由请求镜像策略。它完全优先于虚拟主机和路由配置镜像策略。也就是说，策略不会合并，最具体的非空策略将成为镜像策略。

优先级: (config.core.v3.RoutingPriority) 可选地指定路由优先级。

速率限制: (**重复** config.route.v3.RateLimit) 指定可以应用于路由的一组速率限制配置。

包含 vh 速率限制

(BoolValue) 指定速率限制过滤器是否应包含虚拟主机速率限制。默认情况下，如果路由配置了速率限制，则不会将虚拟主机 rate_limits 应用于请求。

此字段已弃用。请使用 vh_rate_limits

哈希策略: (**重复** config.route.v3.RouteAction.HashPolicy) 指定用于环形哈希负载均衡的一组哈希策略。每个哈希策略都会单独进行评估，组合后的结果将用于路由请求。组合方法是确定性的，这样相同的哈希策略列表将生成相同的哈希值。由于哈希策略检查请求的特定部分，因此它可能无法生成哈希值（例如，如果哈希的标头不存在）。如果（并且仅当）所有配置的哈希策略都无法生成哈希值，则不会为路由生成任何哈希值。在这种情况下，行为与未指定任何哈希策略相同（即环形哈希负载均衡器将选择一个随机后端）。如果哈希策略的“终端”属性设置为 true，并且已生成哈希值，则立即返回哈希值，忽略其余的哈希策略列表。

CORS: (config.route.v3.CorsPolicy) 表示路由具有 CORS 策略。如果在 Route.typed_per_filter_config 或 WeightedCluster.ClusterWeight.typed_per_filter_config 中找到相关的 CORS 策略，则忽略此字段。

注意

此选项已弃用。请使用 Route.typed_per_filter_config 或 WeightedCluster.ClusterWeight.typed_per_filter_config 来配置 CORS HTTP 过滤器。

最大 gRPC 超时: (Duration) 被 grpc_timeout_header_max 弃用。如果存在，并且请求是 gRPC 请求，请使用 grpc-timeout 标头或其默认值（无穷大），而不是 timeout，但将应用的超时限制为此处指定的最大值。如果配置为 0，则 gRPC 请求的最大允许超时为无穷大。如果根本没有配置，则不会使用 grpc-timeout 标头，gRPC 请求会像任何其他请求一样超时，使用 timeout 或其默认值。这可用于防止由于 gRPC 流式传输模式下 gRPC 请求和响应之间可能存在较长时间间隔而导致意外的上游请求超时。

注意

如果使用 x-envoy-upstream-rq-timeout-ms 指定了超时，则当两者都存在时，它优先于 grpc-timeout 标头。另请参阅 x-envoy-upstream-rq-timeout-ms、x-envoy-upstream-rq-per-try-timeout-ms 以及重试概述。

grpc_timeout_offset: (Duration) 被 grpc_timeout_header_offset 弃用。如果存在，Envoy 将通过从标头中减去提供的持续时间来调整 grpc-timeout 标头提供的超时。这在允许 Envoy 将其全局超时设置为低于调用客户端施加的截止时间方面很有用，这使得 Envoy 更有可能处理超时，而不是让调用被客户端取消。仅当提供的 grpc_timeout 大于偏移量时才会应用偏移量。这确保偏移量只会降低超时，而不会将其设置为 0（表示无穷大）。

升级配置: (**重复** config.route.v3.RouteAction.UpgradeConfig)

内部重定向策略: (config.route.v3.InternalRedirectPolicy) 如果存在，Envoy 将尝试跟踪上游重定向响应，而不是将响应代理回下游。上游重定向响应由 redirect_response_codes 定义。

内部重定向操作: (config.route.v3.RouteAction.InternalRedirectAction)

最大内部重定向

(UInt32Value) 处理内部重定向，当且仅当下游请求遇到的先前内部重定向次数低于此值，并且 internal_redirect_action 设置为 HANDLE_INTERNAL_REDIRECT。在下游请求因内部重定向而在多个路由之间来回弹跳的情况下，第一个达到此阈值或 internal_redirect_action 设置为 PASS_THROUGH_INTERNAL_REDIRECT 的路由将重定向传递回下游。

如果没有指定，最多会跟踪一个重定向。

对冲策略: (config.route.v3.HedgePolicy) 表示路由具有对冲策略。请注意，如果设置了此策略，它将完全优先于虚拟主机级别的对冲策略（例如：策略不会合并，最内部的策略将成为强制执行的策略）。

最大流持续时间: (config.route.v3.RouteAction.MaxStreamDuration) 指定此路由的最大流持续时间。

config.route.v3.RouteAction.RequestMirrorPolicy

[config.route.v3.RouteAction.RequestMirrorPolicy proto]

路由器能够将流量从一个集群镜像到另一个集群。当前的实现是“开火即忘”，这意味着 Envoy 不会等待影子集群响应，然后才会返回主集群的响应。所有正常统计信息都会为影子集群收集，这使得此功能对于测试非常有用。

在镜像期间，主机/授权标头会发生更改，以便附加 -shadow。这对于记录很有用。例如，cluster1 变成 cluster1-shadow。此行为可以通过将 disable_shadow_host_suffix_append 设置为 true 来禁用。

注意

如果主集群不存在，则不会触发镜像。

注意

镜像不支持 Http CONNECT 和升级。

{
  "cluster": ...,
  "cluster_header": ...,
  "runtime_fraction": {...},
  "trace_sampled": {...},
  "disable_shadow_host_suffix_append": ...
}

cluster: (string) 只能指定 cluster 和 cluster_header 之一。指定将请求镜像到的集群。该集群必须存在于集群管理器配置中。

cluster_header: (string) 只能指定 cluster 和 cluster_header 之一。 Envoy 将通过从请求标头中读取名为 cluster_header 的 HTTP 标头的值来确定要路由到的集群。仅使用标头中的第一个值，如果标头中找不到该值，则不会发生任何影子请求。 Envoy 不会等待影子集群响应，然后才会返回主集群的响应。

注意

在内部，Envoy 始终使用 HTTP/2 的 :authority 头部来表示 HTTP/1 的 Host 头部。因此，如果尝试匹配 Host，请改用 :authority 进行匹配。

注意

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

运行时分数

(config.core.v3.RuntimeFractionalPercent) 如果未指定，则将镜像到目标集群的所有请求。

如果指定，则此字段优先于 runtime_key 字段，并且请求还必须落在此字段指示的匹配百分比范围内。

对于某个分数 N/D，会选择范围 [0,D) 内的随机数。如果该数 <= 分子 N 的值，或者如果键不存在，则使用默认值，请求将被镜像。

跟踪采样: (BoolValue) 确定是否应对跟踪跨度进行采样。默认值为 true。

disable_shadow_host_suffix_append: (bool) 禁用将 -shadow 后缀附加到镜像的 Host 标头。默认值为 false。

config.route.v3.RouteAction.HashPolicy

[config.route.v3.RouteAction.HashPolicy proto]

如果上游集群使用哈希负载均衡器，则指定路由的哈希策略。

{
  "header": {...},
  "cookie": {...},
  "connection_properties": {...},
  "query_parameter": {...},
  "filter_state": {...},
  "terminal": ...
}

标头

(config.route.v3.RouteAction.HashPolicy.Header) 标头哈希策略。

必须精确设置 header、cookie、connection_properties、query_parameter、filter_state 之一。

connection_properties

(config.route.v3.RouteAction.HashPolicy.ConnectionProperties) 连接属性哈希策略。

必须精确设置 header、cookie、connection_properties、query_parameter、filter_state 之一。

query_parameter

(config.route.v3.RouteAction.HashPolicy.QueryParameter) 查询参数哈希策略。

必须精确设置 header、cookie、connection_properties、query_parameter、filter_state 之一。

filter_state

(config.route.v3.RouteAction.HashPolicy.FilterState) 过滤器状态哈希策略。

必须精确设置 header、cookie、connection_properties、query_parameter、filter_state 之一。

terminal

(bool) 该标志用于短路哈希计算。此字段提供了一种“回退”类型的配置：“如果终端策略不起作用，则回退到策略列表的剩余部分”，当终端策略起作用时，它可以节省时间。

如果为 true，并且已经计算出哈希值，则忽略哈希策略列表的剩余部分。例如，如果配置了以下哈希方法

specifier

terminal

Header A

true

Header B

false

Header C

false

如果策略“header A”生成了哈希值，则 generateHash 过程结束，因为它是一个终端策略。

config.route.v3.RouteAction.HashPolicy.Header

[config.route.v3.RouteAction.HashPolicy.Header proto]

{
  "header_name": ...,
  "regex_rewrite": {...}
}

header_name: (string, REQUIRED) 将用于获取哈希键的请求标头的名称。如果请求标头不存在，则不会生成哈希值。

regex_rewrite: (type.matcher.v3.RegexMatchAndSubstitute) 如果指定，请求标头值将被重写并用于生成哈希键。

config.route.v3.RouteAction.HashPolicy.CookieAttribute

[config.route.v3.RouteAction.HashPolicy.CookieAttribute proto]

CookieAttribute 定义了用于为 HTTP cookie 添加额外属性的 API。

{
  "name": ...,
  "value": ...
}

名称: (string, REQUIRED) Cookie 属性的名称。

value: (string) Cookie 属性的可选值。

config.route.v3.RouteAction.HashPolicy.ConnectionProperties

[config.route.v3.RouteAction.HashPolicy.ConnectionProperties proto]

{
  "source_ip": ...
}

source_ip: (bool) 对源 IP 地址进行哈希处理。

config.route.v3.RouteAction.HashPolicy.QueryParameter

[config.route.v3.RouteAction.HashPolicy.QueryParameter proto]

{
  "name": ...
}

名称: (string, REQUIRED) 将用于获取哈希键的 URL 查询参数的名称。如果参数不存在，则不会生成哈希值。查询参数名称区分大小写。如果查询参数重复，则只考虑第一个值。

config.route.v3.RouteAction.HashPolicy.FilterState

[config.route.v3.RouteAction.HashPolicy.FilterState proto]

{
  "key": ...
}

key: (string, REQUIRED) 每请求过滤器状态中的对象的名称，这是一个 Envoy::Hashable 对象。如果与键关联的数据不存在，或者存储的对象不是 Envoy::Hashable，则不会生成哈希值。

config.route.v3.RouteAction.UpgradeConfig

[config.route.v3.RouteAction.UpgradeConfig proto]

允许在每个路由的基础上启用和禁用升级。这会覆盖 HttpConnectionManager 中指定的任何已启用/禁用的升级过滤器链 upgrade_configs，但不会影响其中指定的任何自定义过滤器链。

{
  "upgrade_type": ...,
  "enabled": {...},
  "connect_config": {...}
}

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

enabled: (BoolValue) 确定此路由上是否可以使用升级。默认为 true。

connect_config: (config.route.v3.RouteAction.UpgradeConfig.ConnectConfig) 用于将数据作为原始数据有效负载发送到上游的配置。这用于 CONNECT 请求，当将 CONNECT 有效负载作为原始 TCP 转发时。请注意，CONNECT 支持目前在 Envoy 中被认为是 alpha 版本。

config.route.v3.RouteAction.UpgradeConfig.ConnectConfig

[config.route.v3.RouteAction.UpgradeConfig.ConnectConfig proto]

用于将数据作为原始数据有效负载发送到上游的配置。这用于 CONNECT 或 POST 请求，当将请求有效负载作为原始 TCP 转发时。

{
  "proxy_protocol_config": {...},
  "allow_post": ...
}

proxy_protocol_config: (config.core.v3.ProxyProtocolConfig) 如果存在，代理协议标头将被附加到发送到上游的 CONNECT 有效负载中。

allow_post: (bool) 如果设置，路由也将允许将 POST 有效负载作为原始 TCP 转发。

config.route.v3.RouteAction.MaxStreamDuration

[config.route.v3.RouteAction.MaxStreamDuration proto]

{
  "max_stream_duration": {...},
  "grpc_timeout_header_max": {...},
  "grpc_timeout_header_offset": {...}
}

最大流持续时间: (Duration) 指定路由上允许的最大流持续时间。如果未指定，则使用 max_stream_duration 字段中的值 HttpConnectionManager.common_http_protocol_options。如果此字段明确设置为零，则任何 HttpConnectionManager max_stream_duration 超时将对此路由禁用。

grpc_timeout_header_max: (Duration) 如果存在，并且请求包含 grpc-timeout 标头，则将该值用作 max_stream_duration，但将应用的超时限制为此处指定的最大值。如果设置为 0，则 grpc-timeout 标头将不加修改地使用。

grpc_timeout_header_offset: (Duration) 如果存在，Envoy 将通过从标头中减去提供的持续时间来调整 grpc-timeout 标头提供的超时。这对于允许 Envoy 将其全局超时设置为低于调用客户端强加的截止日期是有用的，这使得 Envoy 更有可能处理超时，而不是由客户端取消调用。如果在应用偏移量后，得到的超时为零或负数，则流将立即超时。

Enum config.route.v3.RouteAction.ClusterNotFoundResponseCode

[config.route.v3.RouteAction.ClusterNotFoundResponseCode proto]

SERVICE_UNAVAILABLE: (DEFAULT) ⁣HTTP 状态代码 - 503 服务不可用。

NOT_FOUND: ⁣HTTP 状态代码 - 404 未找到。

INTERNAL_SERVER_ERROR: ⁣HTTP 状态代码 - 500 内部服务器错误。

Enum config.route.v3.RouteAction.InternalRedirectAction

[config.route.v3.RouteAction.InternalRedirectAction proto]

配置内部重定向行为。

PASS_THROUGH_INTERNAL_REDIRECT: (DEFAULT) ⁣

HANDLE_INTERNAL_REDIRECT: ⁣

config.route.v3.RetryPolicy

[config.route.v3.RetryPolicy proto]

HTTP 重试架构概述.

{
  "retry_on": ...,
  "num_retries": {...},
  "per_try_timeout": {...},
  "per_try_idle_timeout": {...},
  "retry_priority": {...},
  "retry_host_predicate": [],
  "retry_options_predicates": [],
  "host_selection_retry_max_attempts": ...,
  "retriable_status_codes": [],
  "retry_back_off": {...},
  "rate_limited_retry_back_off": {...},
  "retriable_headers": [],
  "retriable_request_headers": []
}

retry_on: (string) 指定重试发生的条件。这些条件与 x-envoy-retry-on 和 x-envoy-retry-grpc-on 中记录的条件相同。

num_retries: (UInt32Value) 指定允许的重试次数。此参数是可选的，默认为 1。这些条件与 x-envoy-max-retries 中记录的条件相同。

per_try_timeout: (Duration) 指定每个重试尝试（包括初始尝试）的非零上游超时。此参数是可选的。应用了与 x-envoy-upstream-rq-per-try-timeout-ms 中记录的相同条件。

注意

如果未指定，Envoy 将使用请求的全局路由超时。因此，当使用 5xx 为基础的重试策略时，超时的请求将不会被重试，因为总超时预算将已被用尽。

per_try_idle_timeout: (Duration) 指定每个重试尝试（包括初始尝试）的的上游空闲超时时间。此参数为可选，如果不存在，则没有每个尝试的空闲超时时间。每个尝试的空闲超时的语义与路由空闲超时和流空闲超时相似，均由 HTTP 连接管理器强制执行。区别在于此空闲超时由路由器对每个单独的尝试强制执行，因此在所有先前过滤器运行之后，而不是在所有先前过滤器运行之前（对于其他空闲超时）。此超时在总请求超时受重试次数和每次尝试超时限制，但希望确保每次尝试都在取得进展的情况下很有用。另请注意，与每次尝试超时类似，此空闲超时不会在整个请求被路由器接收且获得连接池连接之前开始。与每次尝试超时不同的是，响应开始流回下游客户端后，空闲计时器会继续运行。这确保响应数据继续取得进展，而不会使用 HTTP 连接管理器的空闲超时时间之一。

retry_priority: (config.route.v3.RetryPolicy.RetryPriority) 指定 RetryPriority 的实现，用于确定跨用于重试的优先级的负载分配。有关更多详细信息，请参阅重试插件配置。

retry_host_predicate: (repeated config.route.v3.RetryPolicy.RetryHostPredicate) 指定在选择主机以进行重试时将咨询的 RetryHostPredicates 集合。如果任何谓词拒绝主机，将重新尝试主机选择。有关更多详细信息，请参阅重试插件配置。

retry_options_predicates: (repeated config.core.v3.TypedExtensionConfig) 在重试请求之前将应用的重试选项谓词。这些谓词允许在重试之间自定义请求行为。当存在内置扩展时]

host_selection_retry_max_attempts: (int64) 在放弃之前将重新尝试主机选择的最大次数，此时将路由到最后选择的主机。如果未指定，这将默认为重试一次。

retriable_status_codes: (repeated uint32) 除 retry_on 指定的那些之外，还应触发重试的 HTTP 状态代码。

retry_back_off: (config.route.v3.RetryPolicy.RetryBackOff) 指定控制指数重试后退的参数。此参数为可选，在这种情况下，默认基本间隔为 25 毫秒，或者（如果设置），则为 upstream.base_retry_backoff_ms 运行时参数的当前值。默认最大间隔为基本间隔的 10 倍。有关 Envoy 的后退算法的说明，请参阅 x-envoy-max-retries。

rate_limited_retry_back_off: (config.route.v3.RetryPolicy.RateLimitedRetryBackOff) 指定控制在请求被上游服务器限速时使用的重试后退策略的参数。服务器可能会返回一个响应头（如 Retry-After 或 X-RateLimit-Reset），以向客户端提供有关在重试之前等待多长时间的反馈。如果配置了此后退策略，则只要响应包含匹配的头，它将用于代替默认的指数后退策略（使用 retry_back_off 配置）。

retriable_headers: (repeated config.route.v3.HeaderMatcher) 如果 HTTP 响应头出现在响应中，则会触发重试。如果任何头匹配匹配上游响应头，则会触发重试。只有在 'retriable-headers' 重试策略处于活动状态时，才会咨询该字段。

retriable_request_headers: (repeated config.route.v3.HeaderMatcher) 为了尝试重试，HTTP 头必须出现在请求中。

config.route.v3.RetryPolicy.RetryPriority

[config.route.v3.RetryPolicy.RetryPriority proto]

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

名称: (string, REQUIRED)

typed_config

(Any)

提示

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

envoy.retry_priorities.previous_priorities

config.route.v3.RetryPolicy.RetryHostPredicate

[config.route.v3.RetryPolicy.RetryHostPredicate proto]

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

名称: (string, REQUIRED)

typed_config

(Any)

提示

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

config.route.v3.RetryPolicy.RetryBackOff

[config.route.v3.RetryPolicy.RetryBackOff proto]

{
  "base_interval": {...},
  "max_interval": {...}
}

base_interval: (Duration, REQUIRED) 指定重试之间的基本间隔。此参数为必需，并且必须大于零。小于 1 毫秒的值将向上舍入到 1 毫秒。有关 Envoy 的后退算法的说明，请参阅 x-envoy-max-retries。

max_interval: (Duration) 指定重试之间的最大间隔。此参数为可选，但如果设置，必须大于或等于 base_interval。默认值为 base_interval 的 10 倍。有关 Envoy 的后退算法的说明，请参阅 x-envoy-max-retries。

config.route.v3.RetryPolicy.ResetHeader

[config.route.v3.RetryPolicy.ResetHeader proto]

{
  "name": ...,
  "format": ...
}

名称: (string, REQUIRED) 重置头的名称。

注意

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

format: (config.route.v3.RetryPolicy.ResetHeaderFormat) 重置头的格式。

config.route.v3.RetryPolicy.RateLimitedRetryBackOff

[config.route.v3.RetryPolicy.RateLimitedRetryBackOff proto]

当上游服务器限制请求速率时应用的重试后退策略。

给定此配置

rate_limited_retry_back_off:
  reset_headers:
  - name: Retry-After
    format: SECONDS
  - name: X-RateLimit-Reset
    format: UNIX_TIMESTAMP
  max_interval: "300s"

将应用以下算法

如果响应包含头 Retry-After，其值必须为 120（表示在重试之前等待的秒数的整数）。如果是这样，此值将用作后退间隔。

否则，如果响应包含头 X-RateLimit-Reset，其值必须为 1595320702（表示重试时间的整数，作为以秒为单位的 Unix 时间戳）。如果是这样，当前时间将从该值中减去，结果将用作后退间隔。

否则，Envoy 将使用默认的指数后退策略。

无论使用哪种格式，如果生成的后退间隔超过 max_interval，它将被丢弃，并将尝试 reset_headers 中的下一个头。如果为路由配置了请求超时，它将进一步限制请求允许运行的时间。

为了防止许多客户端在同一时间点重试，会在后退间隔中添加抖动，因此生成的间隔将通过以下方式决定：random(interval, interval * 1.5)。

注意

配置 rate_limited_retry_back_off 本身不会导致请求被重试。您仍然需要配置正确的重试策略以匹配来自上游服务器的响应。

{
  "reset_headers": [],
  "max_interval": {...}
}

reset_headers: (repeated config.route.v3.RetryPolicy.ResetHeader, REQUIRED) 指定要与响应匹配的重置头（如 Retry-After 或 X-RateLimit-Reset）。头按顺序尝试，并区分大小写匹配。第一个成功解析的头将被使用。如果没有任何头匹配，则将改用默认的指数后退。

max_interval: (Duration) 指定 Envoy 允许的最大后退间隔。如果重置头包含一个比这更长的间隔，则它将被丢弃，并将尝试下一个头。默认为 300 秒。

Enum config.route.v3.RetryPolicy.ResetHeaderFormat

[config.route.v3.RetryPolicy.ResetHeaderFormat proto]

SECONDS: (DEFAULT) ⁣

UNIX_TIMESTAMP: ⁣

config.route.v3.HedgePolicy

[config.route.v3.HedgePolicy proto]

HTTP 请求对冲架构概述。

{
  "hedge_on_per_try_timeout": ...
}

hedge_on_per_try_timeout

(bool) 指示在每次尝试超时时应发送对冲请求。这意味着将发出重试，而不会重置原始请求，从而使多个上游请求处于活动状态。第一个成功完成的请求将是返回给调用者的请求。

在任何时候，都会将成功响应（即不会触发任何 retry-on 条件）返回给客户端。
在每次尝试超时之前，错误响应（根据 retry-on 条件）将立即重试，或者如果不再有重试，则返回给客户端。
在每次尝试超时后，错误响应将被丢弃，因为已经有一个以对冲请求形式的重试正在进行。

注意：要使此设置生效，您必须有一个 RetryPolicy，它至少重试一个错误代码并指定最大重试次数。

默认值为 false。

config.route.v3.RedirectAction

[config.route.v3.RedirectAction proto]

{
  "https_redirect": ...,
  "scheme_redirect": ...,
  "host_redirect": ...,
  "port_redirect": ...,
  "path_redirect": ...,
  "prefix_rewrite": ...,
  "regex_rewrite": {...},
  "response_code": ...,
  "strip_query": ...
}

https_redirect

(bool) URL 的方案部分将替换为“https”。

当方案重定向发生时，以下规则适用

如果源 URI 方案是 http 并且端口显式设置为 :80，则端口将在重定向后被删除
如果源 URI 方案是 https 并且端口显式设置为 :443，则端口将在重定向后被删除

只能设置 https_redirect 或 scheme_redirect 之一。

scheme_redirect

(string) URL 的方案部分将替换为该值。

当方案重定向发生时，以下规则适用

如果源 URI 方案是 http 并且端口显式设置为 :80，则端口将在重定向后被删除
如果源 URI 方案是 https 并且端口显式设置为 :443，则端口将在重定向后被删除

只能设置 https_redirect 或 scheme_redirect 之一。

host_redirect: (string) URL 的主机部分将替换为该值。

port_redirect: (uint32) URL 的端口值将替换为该值。

path_redirect

(string) URL 的路径部分将替换为该值。请注意，path_redirect 中的查询字符串将覆盖请求的查询字符串，并且不会被剥离。

例如，假设我们有以下路由

match: { path: “/old-path-1” } redirect: { path_redirect: “/new-path-1” }
match: { path: “/old-path-2” } redirect: { path_redirect: “/new-path-2”, strip-query: “true” }
match: { path: “/old-path-3” } redirect: { path_redirect: “/new-path-3?foo=1”, strip_query: “true” }

如果请求 URI 为“/old-path-1?bar=1”，用户将被重定向到“/new-path-1?bar=1”
如果请求 URI 为“/old-path-2?bar=1”，用户将被重定向到“/new-path-2”
如果请求 URI 为“/old-path-3?bar=1”，用户将被重定向到“/new-path-3?foo=1”

只能设置 path_redirect、prefix_rewrite 或 regex_rewrite 之一。

prefix_rewrite

(string) 指示在重定向期间，匹配的 prefix（或路径）应该替换为该值。此选项允许根据请求动态创建重定向 URL。

注意

请注意 RouteAction 的 prefix_rewrite 中提到的尾部斜杠的使用。

只能设置 path_redirect、prefix_rewrite 或 regex_rewrite 之一。

regex_rewrite

(type.matcher.v3.RegexMatchAndSubstitute) 指示在重定向期间，匹配模式的路径部分应该被重写，甚至允许将模式中的捕获组替换为重写替换字符串中指定的新的路径。这对于允许以了解具有可变内容（如标识符）的段的方式重写应用程序路径很有用。

使用 Google 的 RE2 引擎的示例

路径模式 ^/service/([^/]+)(/.*)$ 与替换字符串 \2/instance/\1 配对，将 /service/foo/v1/api 转换为 /v1/api/instance/foo。
模式 one 与替换字符串 two 配对，将 /xxx/one/yyy/one/zzz 转换为 /xxx/two/yyy/two/zzz。
模式 ^(.*?)one(.*)$ 与替换字符串 \1two\2 配对，将只替换 one 的第一个出现，将路径 /xxx/one/yyy/one/zzz 转换为 /xxx/two/yyy/one/zzz。
模式 (?i)/xxx/ 与替换字符串 /yyy/ 配对，将进行不区分大小写的匹配，并将路径 /aaa/XxX/bbb 转换为 /aaa/yyy/bbb。

只能设置 path_redirect、prefix_rewrite 或 regex_rewrite 之一。

response_code: (config.route.v3.RedirectAction.RedirectResponseCode) 在重定向响应中使用的 HTTP 状态代码。默认响应代码是 MOVED_PERMANENTLY (301)。

strip_query: (bool) 指示在重定向期间，URL 的查询部分将被删除。默认值为 false。

Enum config.route.v3.RedirectAction.RedirectResponseCode

[config.route.v3.RedirectAction.RedirectResponseCode proto]

MOVED_PERMANENTLY: (DEFAULT) ⁣永久移动 HTTP 状态代码 - 301。

FOUND: ⁣找到 HTTP 状态代码 - 302。

SEE_OTHER: ⁣查看其他 HTTP 状态代码 - 303。

TEMPORARY_REDIRECT: ⁣临时重定向 HTTP 状态代码 - 307。

PERMANENT_REDIRECT: ⁣永久重定向 HTTP 状态代码 - 308。

config.route.v3.DirectResponseAction

[config.route.v3.DirectResponseAction proto]

{
  "status": ...,
  "body": {...}
}

status: (uint32) 指定要返回的 HTTP 响应状态。

body: (config.core.v3.DataSource) 指定响应正文的内容。如果省略此设置，则生成的响应中不会包含任何正文。

注意

可以使用包含的 config.route.v3.Route、config.route.v3.RouteConfiguration 或 config.route.v3.VirtualHost 中的 response_headers_to_add 指定标头。

config.route.v3.Decorator

[config.route.v3.Decorator proto]

{
  "operation": ...,
  "propagate": {...}
}

operation: (string, REQUIRED) 与匹配此路由的请求关联的操作名称。如果启用了跟踪，则此信息将用作为此请求报告的跨度名称。

注意

对于入站（入站）请求或出站（出站）响应，此值可能会被 x-envoy-decorator-operation 标头覆盖。

propagate: (BoolValue) 是否应将装饰的详细信息传播到另一方。默认值为 true。

config.route.v3.Tracing

[config.route.v3.Tracing proto]

{
  "client_sampling": {...},
  "random_sampling": {...},
  "overall_sampling": {...},
  "custom_tags": []
}

client_sampling: (type.v3.FractionalPercent) 由此 HTTP 连接管理器管理的请求的目标百分比，如果设置了 x-client-trace-id 标头，将强制跟踪这些请求。此字段与 HTTP 连接管理器中的运行时变量“tracing.client_enabled”直接对应。默认值：100%

random_sampling: (type.v3.FractionalPercent) 由此 HTTP 连接管理器管理的请求的目标百分比，如果未被客户端请求或未强制执行，将随机选择这些请求进行跟踪生成。此字段与 HTTP 连接管理器中的运行时变量“tracing.random_sampling”直接对应。默认值：100%

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

custom_tags: (repeated type.tracing.v3.CustomTag) 具有唯一标签名称的自定义标签列表，用于为活动跨度创建标签。它将在与 HTTP 连接管理器中配置的相应配置合并后生效。如果在 HTTP 连接管理器和路由级别分别配置了两个具有相同名称的标签，则这里配置的标签优先。

config.route.v3.VirtualCluster

[config.route.v3.VirtualCluster proto]

虚拟集群是一种方法，可以针对某些重要端点指定正则表达式匹配规则，以便为匹配的请求显式生成统计信息。这样做的原因是，在执行 prefix/path 匹配时，Envoy 并不总是知道应用程序认为端点是什么。因此，Envoy 无法以通用方式发出每个端点的统计信息。但是，系统通常具有希望获取“完美”统计信息的极其关键的端点。虚拟集群统计信息是完美的，因为它们是在下游侧发出的，因此它们包括网络级别的故障。

有关虚拟集群统计信息的文档。

注意

虚拟集群是一个有用的工具，但我们不建议为每个应用程序端点设置一个虚拟集群。这既难以维护，而且匹配和统计输出也不是免费的。

{
  "headers": [],
  "name": ...
}

头部: (repeated config.route.v3.HeaderMatcher) 指定用于匹配请求的标头匹配器列表。每个指定的标头都必须匹配。伪标头 :path 和 :method 可用于分别匹配请求路径和方法。

名称: (string, REQUIRED) 指定虚拟集群的名称。虚拟集群名称和虚拟主机名称在发出统计信息时使用。统计信息由路由器过滤器发出，并在此处进行说明。

config.route.v3.RateLimit

[config.route.v3.RateLimit proto]

全局限流架构概述。也适用于本地限流使用描述符.

{
  "stage": {...},
  "disable_key": ...,
  "actions": [],
  "limit": {...}
}

阶段: (UInt32Value) 指的是过滤器中设置的阶段。限流配置仅适用于具有相同阶段编号的过滤器。默认阶段编号为 0。

注意

该过滤器支持 0 到 10（含）的阶段编号范围。

禁用键: (string) 用于在运行时设置以禁用此限流配置的键。

操作: (repeated config.route.v3.RateLimit.Action, REQUIRED) 要应用于此限流配置的操作列表。顺序很重要，因为操作按顺序处理，并且描述符是通过按该顺序追加描述符条目来组成的。如果操作无法追加描述符条目，则不会为该配置生成描述符。有关更多文档，请参阅组合操作。

限制: (config.route.v3.RateLimit.Override) 要追加到此限流配置生成的描述符的可选限制覆盖。如果覆盖值无效或无法从元数据解析，则不会提供覆盖。有关更多信息，请参阅限流覆盖。

config.route.v3.RateLimit.Action

[config.route.v3.RateLimit.Action proto]

{
  "source_cluster": {...},
  "destination_cluster": {...},
  "request_headers": {...},
  "remote_address": {...},
  "generic_key": {...},
  "header_value_match": {...},
  "dynamic_metadata": {...},
  "metadata": {...},
  "extension": {...},
  "masked_remote_address": {...},
  "query_parameter_value_match": {...}
}

源集群

(config.route.v3.RateLimit.Action.SourceCluster) 对源集群进行限流。

必须设置 source_cluster、destination_cluster、request_headers、remote_address、generic_key、header_value_match、dynamic_metadata、metadata、extension、masked_remote_address、query_parameter_value_match 中的某一项。

目标集群

(config.route.v3.RateLimit.Action.DestinationCluster) 对目标集群进行限流。

必须设置 source_cluster、destination_cluster、request_headers、remote_address、generic_key、header_value_match、dynamic_metadata、metadata、extension、masked_remote_address、query_parameter_value_match 中的某一项。

请求头

(config.route.v3.RateLimit.Action.RequestHeaders) 对请求头进行限流。

必须设置 source_cluster、destination_cluster、request_headers、remote_address、generic_key、header_value_match、dynamic_metadata、metadata、extension、masked_remote_address、query_parameter_value_match 中的某一项。

远程地址

(config.route.v3.RateLimit.Action.RemoteAddress) 对远程地址进行限流。

必须设置 source_cluster、destination_cluster、request_headers、remote_address、generic_key、header_value_match、dynamic_metadata、metadata、extension、masked_remote_address、query_parameter_value_match 中的某一项。

通用键

(config.route.v3.RateLimit.Action.GenericKey) 对通用键进行限流。

必须设置 source_cluster、destination_cluster、request_headers、remote_address、generic_key、header_value_match、dynamic_metadata、metadata、extension、masked_remote_address、query_parameter_value_match 中的某一项。

头值匹配

(config.route.v3.RateLimit.Action.HeaderValueMatch) 对请求头的存在进行限流。

必须设置 source_cluster、destination_cluster、request_headers、remote_address、generic_key、header_value_match、dynamic_metadata、metadata、extension、masked_remote_address、query_parameter_value_match 中的某一项。

dynamic_metadata

(config.route.v3.RateLimit.Action.DynamicMetaData) 对动态元数据进行限流。

注意

此字段已弃用，建议使用 metadata 字段。

必须设置 source_cluster、destination_cluster、request_headers、remote_address、generic_key、header_value_match、dynamic_metadata、metadata、extension、masked_remote_address、query_parameter_value_match 中的某一项。

元数据

(config.route.v3.RateLimit.Action.MetaData) 对元数据进行限流。

必须设置 source_cluster、destination_cluster、request_headers、remote_address、generic_key、header_value_match、dynamic_metadata、metadata、extension、masked_remote_address、query_parameter_value_match 中的某一项。

扩展

(config.core.v3.TypedExtensionConfig) 限流描述符扩展。请参阅限流描述符扩展文档。

HTTP 匹配输入函数允许作为描述符扩展。只有在没有与类型 URL 匹配的限流描述符扩展时，才会查找输入函数。

提示

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

envoy.rate_limit_descriptors.expr

必须设置 source_cluster、destination_cluster、request_headers、remote_address、generic_key、header_value_match、dynamic_metadata、metadata、extension、masked_remote_address、query_parameter_value_match 中的某一项。

屏蔽远程地址

(config.route.v3.RateLimit.Action.MaskedRemoteAddress) 对屏蔽的远程地址进行限流。

必须设置 source_cluster、destination_cluster、request_headers、remote_address、generic_key、header_value_match、dynamic_metadata、metadata、extension、masked_remote_address、query_parameter_value_match 中的某一项。

查询参数值匹配

(config.route.v3.RateLimit.Action.QueryParameterValueMatch) 对查询参数的存在进行限流。

必须设置 source_cluster、destination_cluster、request_headers、remote_address、generic_key、header_value_match、dynamic_metadata、metadata、extension、masked_remote_address、query_parameter_value_match 中的某一项。

config.route.v3.RateLimit.Action.SourceCluster

[config.route.v3.RateLimit.Action.SourceCluster proto]

以下描述符条目将附加到描述符中

("source_cluster", "<local service cluster>")

<本地服务集群> 来自 --service-cluster 选项。

config.route.v3.RateLimit.Action.DestinationCluster

[config.route.v3.RateLimit.Action.DestinationCluster proto]

以下描述符条目将附加到描述符中

("destination_cluster", "<routed target cluster>")

一旦请求与路由表规则匹配，就会通过以下路由表配置设置之一确定路由集群

cluster 指示要路由到的上游集群。
weighted_clusters 从一组带有属性权重的集群中随机选择一个集群。
cluster_header 指示请求中哪个头包含目标集群。

config.route.v3.RateLimit.Action.RequestHeaders

[config.route.v3.RateLimit.Action.RequestHeaders proto]

当头包含与 header_name 匹配的键时，将追加以下描述符条目

("<descriptor_key>", "<header_value_queried_from_header>")

{
  "header_name": ...,
  "descriptor_key": ...,
  "skip_if_absent": ...
}

header_name: (string, REQUIRED) 要从请求头中查询的头名称。头的值用于填充描述符条目中描述符键的值。

描述符键: (string, REQUIRED) 要在描述符条目中使用的键。

如果不存在则跳过: (bool) 如果设置为 true，则 Envoy 在请求中不存在头时调用限流服务时会跳过描述符。默认情况下，如果请求中不存在此头，则会跳过调用限流服务。

config.route.v3.RateLimit.Action.RemoteAddress

[config.route.v3.RateLimit.Action.RemoteAddress proto]

以下描述符条目将附加到描述符中，并使用来自 x-forwarded-for 的受信任地址填充。

("remote_address", "<trusted address from x-forwarded-for>")

config.route.v3.RateLimit.Action.MaskedRemoteAddress

[config.route.v3.RateLimit.Action.MaskedRemoteAddress proto]

以下描述符条目将附加到描述符中，并使用来自 x-forwarded-for 的屏蔽地址填充。

("masked_remote_address", "<masked address from x-forwarded-for>")

{
  "v4_prefix_mask_len": {...},
  "v6_prefix_mask_len": {...}
}

v4_prefix_mask_len: (UInt32Value) IPv4 的前缀掩码长度（例如 0、32）。未设置时默认为 32。例如，来自 x-forwarded-for 的受信任地址为 192.168.1.1，则描述符条目为（“masked_remote_address”，“192.168.1.1/32”）；如果掩码长度为 24，则描述符条目为（“masked_remote_address”，“192.168.1.0/24”）。

v6_prefix_mask_len: (UInt32Value) IPv6 的前缀掩码长度（例如 0、128）。未设置时默认为 128。例如，来自 x-forwarded-for 的受信任地址为 2001:abcd:ef01:2345:6789:abcd:ef01:234，则描述符条目为（“masked_remote_address”，“2001:abcd:ef01:2345:6789:abcd:ef01:234/128”）；如果掩码长度为 64，则描述符条目为（“masked_remote_address”，“2001:abcd:ef01:2345::/64”）。

config.route.v3.RateLimit.Action.GenericKey

[config.route.v3.RateLimit.Action.GenericKey proto]

以下描述符条目将附加到描述符中

("generic_key", "<descriptor_value>")

{
  "descriptor_value": ...,
  "descriptor_key": ...
}

描述符值: (string, REQUIRED) 要在描述符条目中使用的值。

描述符键: (string) 要在描述符条目中使用的可选键。如果未设置，则默认为 ‘generic_key’ 作为描述符键。

config.route.v3.RateLimit.Action.HeaderValueMatch

[config.route.v3.RateLimit.Action.HeaderValueMatch proto]

以下描述符条目将附加到描述符中

("header_match", "<descriptor_value>")

{
  "descriptor_key": ...,
  "descriptor_value": ...,
  "expect_match": {...},
  "headers": []
}

描述符键: (string) 要在描述符条目中使用的键。默认为 header_match。

描述符值: (string, REQUIRED) 要在描述符条目中使用的值。

预期匹配: (BoolValue) 如果设置为 true，则当请求与头匹配时，操作将追加描述符条目。如果设置为 false，则当请求与头不匹配时，操作将追加描述符条目。默认值为 true。

头部: (repeated config.route.v3.HeaderMatcher, REQUIRED) 指定限流操作应匹配的一组头。该操作将根据配置中指定的所有头来检查请求的头。如果配置中的所有头都存在于请求中，且值相同（或基于是否存在，如果值字段不在配置中），则将发生匹配。

config.route.v3.RateLimit.Action.DynamicMetaData

[config.route.v3.RateLimit.Action.DynamicMetaData proto]

当动态元数据包含键值时，将追加以下描述符条目

("<descriptor_key>", "<value_queried_from_dynamic_metadata>")

注意

此操作已弃用，建议使用 metadata 操作

{
  "descriptor_key": ...,
  "metadata_key": {...},
  "default_value": ...
}

描述符键: (string, REQUIRED) 要在描述符条目中使用的键。

元数据键: (type.metadata.v3.MetadataKey, REQUIRED) 定义用于检索字符串值的键和路径的元数据结构。只有当动态元数据中的值为字符串类型时，才会发生匹配。

default_value: (string) 如果 metadata_key 为空，则使用可选值。如果未设置且元数据键下没有值，则不会生成描述符。

config.route.v3.RateLimit.Action.MetaData

[config.route.v3.RateLimit.Action.MetaData proto]

当元数据包含键值时，将追加以下描述符条目

("<descriptor_key>", "<value_queried_from_metadata>")

{
  "descriptor_key": ...,
  "metadata_key": {...},
  "default_value": ...,
  "source": ...,
  "skip_if_absent": ...
}

描述符键: (string, REQUIRED) 要在描述符条目中使用的键。

元数据键: (type.metadata.v3.MetadataKey, REQUIRED) 定义用于检索字符串值的键和路径的元数据结构。只有当元数据中的值为字符串类型时，才会发生匹配。

default_value: (string) 如果 metadata_key 为空，则使用可选值。如果未设置且元数据键下没有值，则将遵循 skip_if_absent 以跳过调用限速服务或跳过描述符。

source: (config.route.v3.RateLimit.Action.MetaData.Source) 元数据的来源

如果不存在则跳过: (bool) 如果设置为 true，当 metadata_key 为空且 default_value 未设置时，Envoy 会在调用限速服务时跳过描述符。默认情况下，它会在这种情况下跳过调用限速服务。

Enum config.route.v3.RateLimit.Action.MetaData.Source

[config.route.v3.RateLimit.Action.MetaData.Source proto]

DYNAMIC: (DEFAULT) ⁣查询动态元数据

ROUTE_ENTRY: ⁣查询路由条目元数据

config.route.v3.RateLimit.Action.QueryParameterValueMatch

[config.route.v3.RateLimit.Action.QueryParameterValueMatch proto]

以下描述符条目将附加到描述符中

("query_match", "<descriptor_value>")

{
  "descriptor_key": ...,
  "descriptor_value": ...,
  "expect_match": {...},
  "query_parameters": []
}

描述符键: (string) 描述符条目中使用的键。默认值为 query_match。

描述符值: (string, REQUIRED) 要在描述符条目中使用的值。

预期匹配: (BoolValue) 如果设置为 true，则当请求与头匹配时，操作将追加描述符条目。如果设置为 false，则当请求与头不匹配时，操作将追加描述符条目。默认值为 true。

查询参数: (repeated config.route.v3.QueryParameterMatcher, REQUIRED) 指定限速操作应匹配的一组查询参数。该操作将检查请求的查询参数与配置中指定的所有查询参数。如果配置中的所有查询参数都存在于请求中，并且具有相同的值（或者基于存在，如果值字段不在配置中），则会发生匹配。

config.route.v3.RateLimit.Override

[config.route.v3.RateLimit.Override proto]

{
  "dynamic_metadata": {...}
}

dynamic_metadata: (config.route.v3.RateLimit.Override.DynamicMetadata, REQUIRED) 来自动态元数据的限速覆盖。

config.route.v3.RateLimit.Override.DynamicMetadata

[config.route.v3.RateLimit.Override.DynamicMetadata proto]

从动态元数据中获取覆盖。

{
  "metadata_key": {...}
}

元数据键: (type.metadata.v3.MetadataKey, REQUIRED) 定义用于检索结构体值的键和路径的元数据结构。该值必须是一个结构体，其中包含一个整数“requests_per_unit”属性和一个“unit”属性，其值可解析为 RateLimitUnit 枚举

config.route.v3.HeaderMatcher

[config.route.v3.HeaderMatcher proto]

注意

在内部，Envoy 始终使用 HTTP/2 的 :authority 头部来表示 HTTP/1 的 Host 头部。因此，如果尝试匹配 Host，请改用 :authority 进行匹配。

注意

要根据 HTTP 方法路由，请使用特殊的 HTTP/2 :method 标头。这适用于 HTTP/1 和 HTTP/2，因为 Envoy 会规范化标头。例如：

{
  "name": ":method",
  "string_match": {
    "exact": "POST"
  }
}

注意

在没有标头匹配规范的情况下，匹配将默认为 present_match。即，具有 name 标头的请求将匹配，无论标头值是什么。

{
  "name": ...,
  "exact_match": ...,
  "safe_regex_match": {...},
  "range_match": {...},
  "present_match": ...,
  "prefix_match": ...,
  "suffix_match": ...,
  "contains_match": ...,
  "string_match": {...},
  "invert_match": ...,
  "treat_missing_header_as_empty": ...
}

名称: (string, REQUIRED) 指定请求中标头的名称。

exact_match

(string) 如果指定，则标头匹配将基于标头的值进行执行。此字段已弃用。请使用 string_match。

指定将如何执行标头匹配以路由请求。

只能设置 exact_match、safe_regex_match、range_match、present_match、prefix_match、suffix_match、contains_match、string_match 中的一个。

safe_regex_match

(type.matcher.v3.RegexMatcher) 如果指定，则此正则表达式字符串是正则表达式规则，这意味着整个请求标头值必须与正则表达式匹配。如果请求标头值的子序列与正则表达式匹配，则规则将不匹配。此字段已弃用。请使用 string_match。

指定将如何执行标头匹配以路由请求。

只能设置 exact_match、safe_regex_match、range_match、present_match、prefix_match、suffix_match、contains_match、string_match 中的一个。

range_match

(type.v3.Int64Range) 如果指定，则标头匹配将基于范围执行。如果请求标头值在此范围内，则规则将匹配。整个请求标头值必须表示一个以基数 10 表示的整数：由一个可选的正号或负号后跟一个数字序列组成。如果标头值不表示整数，则规则将不匹配。对于空值、浮点数或仅标头值的子序列是整数，匹配将失败。

示例

对于范围 [-10,0)，路由将匹配标头值 -1，但不匹配 0、somestring、10.9、-1somestring

指定将如何执行标头匹配以路由请求。

只能设置 exact_match、safe_regex_match、range_match、present_match、prefix_match、suffix_match、contains_match、string_match 中的一个。

present_match

(bool) 如果指定为 true，则标头匹配将基于标头是否在请求中执行。如果指定为 false，则标头匹配将基于标头是否不存在执行。

指定将如何执行标头匹配以路由请求。

只能设置 exact_match、safe_regex_match、range_match、present_match、prefix_match、suffix_match、contains_match、string_match 中的一个。

prefix_match

(string) 如果指定，则标头匹配将基于标头值的前缀执行。注意：不允许空前缀，请改用 present_match。此字段已弃用。请使用 string_match。

示例

前缀 abcd 匹配值 abcdxyz，但不匹配 abcxyz。

指定将如何执行标头匹配以路由请求。

只能设置 exact_match、safe_regex_match、range_match、present_match、prefix_match、suffix_match、contains_match、string_match 中的一个。

suffix_match

(string) 如果指定，则标头匹配将基于标头值的后缀执行。注意：不允许空后缀，请改用 present_match。此字段已弃用。请使用 string_match。

示例

后缀 abcd 匹配值 xyzabcd，但不匹配 xyzbcd。

指定将如何执行标头匹配以路由请求。

只能设置 exact_match、safe_regex_match、range_match、present_match、prefix_match、suffix_match、contains_match、string_match 中的一个。

contains_match

(string) 如果指定，则标头匹配将基于标头值是否包含给定值执行。注意：不允许空包含匹配，请改用 present_match。此字段已弃用。请使用 string_match。

示例

值 abcd 匹配值 xyzabcdpqr，但不匹配 xyzbcdpqr。

指定将如何执行标头匹配以路由请求。

只能设置 exact_match、safe_regex_match、range_match、present_match、prefix_match、suffix_match、contains_match、string_match 中的一个。

string_match

(type.matcher.v3.StringMatcher) 如果指定，则标头匹配将基于标头值的字符串匹配执行。

指定将如何执行标头匹配以路由请求。

只能设置 exact_match、safe_regex_match、range_match、present_match、prefix_match、suffix_match、contains_match、string_match 中的一个。

invert_match

(bool) 如果指定，则匹配结果将在检查之前反转。默认为 false。

示例

正则表达式 \d{3} 不匹配值 1234，因此在反转时将匹配。
范围 [-10,0) 将匹配值 -1，因此在反转时将不匹配。

treat_missing_header_as_empty

(bool) 如果指定，则对于任何标头匹配规则，如果标头匹配规则指定的标头不存在，则此标头值将被视为为空。默认为 false。

示例

标头匹配规则指定的标头“header1”到范围匹配 [0, 10]，invert_match 设置为 true，treat_missing_header_as_empty 设置为 true；“header1”标头不存在。匹配规则将把“header1”视为一个空标头。空标头不匹配范围，因此在反转时将匹配。
标头匹配规则指定的标头“header2”到范围匹配 [0, 10]，invert_match 设置为 true，treat_missing_header_as_empty 设置为 false；“header2”标头不存在，并且将忽略“header2”的标头匹配器规则，因此它将不匹配。
标头匹配规则指定的标头“header3”到字符串正则表达式匹配 ^$，这意味着一个空字符串，并且 treat_missing_header_as_empty 设置为 true；“header3”标头不存在。匹配规则将把“header3”标头视为一个空标头，因此它将匹配。
标头匹配规则指定标头“header4”与字符串正则表达式匹配^$，这意味着一个空字符串，并且treat_missing_header_as_empty设置为false；标头“header4”不存在。因此将忽略“header4”的匹配规则，它不会匹配。

config.route.v3.QueryParameterMatcher

[config.route.v3.QueryParameterMatcher proto]

查询参数匹配将请求的:path 标头的查询字符串视为一个由与号分隔的键和/或键=值元素列表。

{
  "name": ...,
  "string_match": {...},
  "present_match": ...
}

名称: (string, REQUIRED) 指定请求的path的查询字符串中必须存在的键的名称。

string_match

(type.matcher.v3.StringMatcher) 指定查询参数值是否应与字符串匹配。

只能设置string_match或present_match中的一个。

present_match

(bool) 指定查询参数是否应该存在。

只能设置string_match或present_match中的一个。

config.route.v3.InternalRedirectPolicy

[config.route.v3.InternalRedirectPolicy proto]

HTTP 内部重定向架构概述.

{
  "max_internal_redirects": {...},
  "redirect_response_codes": [],
  "predicates": [],
  "allow_cross_scheme_redirect": ...,
  "response_headers_to_copy": []
}

最大内部重定向

(UInt32Value) 除非下游请求遇到的先前内部重定向次数低于此值，否则不会处理内部重定向。在下游请求因内部重定向而在多个路由之间弹跳的情况下，第一个达到此阈值或未设置internal_redirect_policy的路由将把重定向传递回下游。

如果没有指定，最多会跟踪一个重定向。

redirect_response_codes: (repeated uint32) 定义允许哪些上游响应代码触发内部重定向。如果未指定，则只有 302 将被视为内部重定向。仅 301、302、303、307 和 308 是有效值。任何其他代码都将被忽略。

predicates

(repeated config.core.v3.TypedExtensionConfig) 指定在上游响应被所有其他条件视为触发内部重定向时查询的谓词列表。列表中的任何谓词都可以拒绝重定向，从而导致响应被代理到下游。

提示

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

allow_cross_scheme_redirect: (bool) 允许内部重定向遵循与 x-forwarded-proto 值不同的方案的目标 URI。默认值为 false。

response_headers_to_copy: (repeated string) 指定要从内部重定向复制到后续请求的标头名称列表。如果在此处指定标头，但在重定向中不存在，则它将在后续请求中被清除。

config.route.v3.FilterConfig

[config.route.v3.FilterConfig proto]

HTTP 过滤器配置的简单包装器。这旨在用作VirtualHost.typed_per_filter_config、Route.typed_per_filter_config或WeightedCluster.ClusterWeight.typed_per_filter_config中 map 值的包装器，以便向过滤器添加其他标志。

{
  "config": {...},
  "is_optional": ...,
  "disabled": ...
}

config: (Any) 过滤器配置。

是否可选: (bool) 如果为真，则过滤器是可选的，这意味着如果客户端不支持指定的过滤器，它可以忽略 map 条目，而不是拒绝配置。

disabled: (bool) 如果为真，则过滤器在路由或虚拟主机中被禁用，并且config字段将被忽略。有关更多详细信息，请参阅基于路由的过滤器链.

注意

此字段将在请求到达并为请求创建过滤器链时生效。如果为请求选择了初始路由，并且在初始路由中禁用了过滤器，则不会将过滤器添加到过滤器链中。如果请求稍后被修改并重新匹配到另一个路由，则由初始路由禁用的过滤器不会被添加回过滤器链，因为过滤器链已经创建，现在更改链为时已晚。

此字段目前仅对下游 HTTP 过滤器有意义。

HTTP 路由组件 (proto)

config.route.v3.VirtualHost

枚举 config.route.v3.VirtualHost.TlsRequirementType

config.route.v3.FilterAction

config.route.v3.RouteList

config.route.v3.Route

config.route.v3.WeightedCluster

config.route.v3.WeightedCluster.ClusterWeight

config.route.v3.ClusterSpecifierPlugin

config.route.v3.RouteMatch

config.route.v3.RouteMatch.GrpcRouteMatchOptions

config.route.v3.RouteMatch.TlsContextMatchOptions

config.route.v3.RouteMatch.ConnectMatcher

config.route.v3.CorsPolicy

config.route.v3.RouteAction

config.route.v3.RouteAction.RequestMirrorPolicy

config.route.v3.RouteAction.HashPolicy

config.route.v3.RouteAction.HashPolicy.Header

config.route.v3.RouteAction.HashPolicy.CookieAttribute

config.route.v3.RouteAction.HashPolicy.Cookie

config.route.v3.RouteAction.HashPolicy.ConnectionProperties

config.route.v3.RouteAction.HashPolicy.QueryParameter

config.route.v3.RouteAction.HashPolicy.FilterState

config.route.v3.RouteAction.UpgradeConfig

config.route.v3.RouteAction.UpgradeConfig.ConnectConfig

config.route.v3.RouteAction.MaxStreamDuration

Enum config.route.v3.RouteAction.ClusterNotFoundResponseCode

Enum config.route.v3.RouteAction.InternalRedirectAction

config.route.v3.RetryPolicy

config.route.v3.RetryPolicy.RetryPriority

config.route.v3.RetryPolicy.RetryHostPredicate

config.route.v3.RetryPolicy.RetryBackOff

config.route.v3.RetryPolicy.ResetHeader

config.route.v3.RetryPolicy.RateLimitedRetryBackOff

Enum config.route.v3.RetryPolicy.ResetHeaderFormat

config.route.v3.HedgePolicy

config.route.v3.RedirectAction

Enum config.route.v3.RedirectAction.RedirectResponseCode

config.route.v3.DirectResponseAction

config.route.v3.Decorator

config.route.v3.Tracing

config.route.v3.VirtualCluster

config.route.v3.RateLimit

config.route.v3.RateLimit.Action

config.route.v3.RateLimit.Action.SourceCluster

config.route.v3.RateLimit.Action.DestinationCluster

config.route.v3.RateLimit.Action.RequestHeaders

config.route.v3.RateLimit.Action.RemoteAddress

config.route.v3.RateLimit.Action.MaskedRemoteAddress

config.route.v3.RateLimit.Action.GenericKey

config.route.v3.RateLimit.Action.HeaderValueMatch

config.route.v3.RateLimit.Action.DynamicMetaData

config.route.v3.RateLimit.Action.MetaData

Enum config.route.v3.RateLimit.Action.MetaData.Source

config.route.v3.RateLimit.Action.QueryParameterValueMatch

config.route.v3.RateLimit.Override

config.route.v3.RateLimit.Override.DynamicMetadata

config.route.v3.HeaderMatcher

config.route.v3.QueryParameterMatcher

config.route.v3.InternalRedirectPolicy

config.route.v3.FilterConfig