路由

路由指定请求如何匹配相应的路径以及接下来要做什么(例如,重定向,转发,重写等)的规范。

注意:Envoy支持通过匹配HTTP头中的方法进行路由。

{
  "prefix": "...",
  "path": "...",
  "regex": "...",
  "cluster": "...",
  "cluster_header": "...",
  "weighted_clusters" : "{...}",
  "host_redirect": "...",
  "path_redirect": "...",
  "prefix_rewrite": "...",
  "host_rewrite": "...",
  "auto_host_rewrite": "...",
  "case_sensitive": "...",
  "use_websocket": "...",
  "timeout_ms": "...",
  "runtime": "{...}",
  "retry_policy": "{...}",
  "shadow": "{...}",
  "priority": "...",
  "headers": [],
  "rate_limits": [],
  "include_vh_rate_limits" : "...",
  "hash_policy": "{...}",
  "request_headers_to_add" : [],
  "opaque_config": [],
  "cors": "{...}",
  "decorator" : "{...}"
}
  • prefix
    (sometimes required, string) 如果指定,则路由使用匹配前缀规则,这意味着前缀必须匹配路径头的开始部分。

    注意:必须指定prefixpathregex其中之一。

  • path
    (sometimes required, string) 如果指定,则路由采用一个精确的路径匹配规则,这意味着一旦路径字符串匹配,则将会被移除,

    注意:必须指定prefixpathregex其中之一。

  • regex
    (sometimes required, string) 如果指定,则路由采用正则表达式匹配规则,这意味着一旦路径字符串匹配,则将会被移除,正则表达式必须匹配:path头。整个完整的路径(不含查询字符串)必须匹配正则表达式。如果只有:path头的子序列与正则表达式匹配,则规则上不匹配。这里定义了正则表达式语法

    示例:

    • 正则表达式 /b[io]t 匹配路径 /bit
    • 正则表达式 /b[io]t 匹配路径 /bot
    • 正则表达式 /b[io]t 不匹配路径 /bite
    • 正则表达式 /b[io]t 不匹配路径 /bit/bot

      注意:必须指定prefixpathregex其中之一。

  • cors
    (optional, object) 指定路由的CORS策略。

  • cluster
    (sometimes required, string) 如果不是重定向路由(未指定host_redirectpath_redirect),则必须指定clustercluster_headerweighted_clusters其中之一。指定群集时,其值指示请求应转发到的上游群集。

  • cluster_header
    (sometimes required, string) 如果不是重定向路由(未指定host_redirectpath_redirect),则必须指定clustercluster_headerweighted_clusters其中之一。当指定cluster_header时,Envoy将通过从请求头中读取由cluster_header命名的HTTP头的值,来明确要路由到的集群。如果相应的头没有找到,或者引用的群集不存在,Envoy将返回一个404响应。

    注意:在内部,Envoy始终使用HTTP/2的:authority头来表示HTTP/1主机头。因此,如果在试图匹配主机,应该匹配:authority头。

  • weighted_clusters
    (sometimes required, object) 如果不是重定向路由(未指定host_redirectpath_redirect),则必须指定clustercluster_headerweighted_clusters其中之一。使用weighted_clusters选项,可以为该路由指定多个上游群集。根据每个集群的权重,将请求转发到其中一个上游集群。请参阅流量拆分以获取相应的文档。

  • host_redirect
    (sometimes required, string) 表示该路由是重定向规则。如果匹配,则会发送301重定向的响应,该响应将使用该值交换URL的主机部分。也可以使用path_redirect选项一起指定。

  • path_redirect
    (sometimes required, string) 表示该路由是重定向规则。如果匹配,则会发送一个301重定向的响应,用这个值交换URL的路径部分。可以与host_redirect选项一起指定。路由器过滤器将在重写x-envoy-original-path头之前放置原始路径。

  • prefix_rewrite
    (optional, string) 表示在转发过程中,此值将替换所匹配的前缀(或路径)。当使用正则表达式路径匹配时,将替换整个路径(不包括查询字符串)。此选项允许应用程序的URL与反向代理层公开的路径不同。

  • host_rewrite
    (optional, string) 表示在转发过程中,此值将替换主机头。

  • auto_host_rewrite
    (optional, boolean) 表示在转发过程中,主机头将与群集管理器选择的上游主机的主机名进行交换。此选项仅适用于路由的目标群集的类型为strict_dnslogical_dns。对于其他群集类型,设置为true将无效。auto_host_rewritehost_rewrite是互斥的选项。只能指定一个。

  • case_sensitive
    (optional, boolean) 表示前缀/路径匹配是否区分大小写。默认值是true。

  • use_websocket
    (optional, boolean) 表示是否允许与此路由连接的HTTP/1.1客户端升级到WebSocket连接。默认值是false。

    注意:如果设置为true,Envoy期望与此路由匹配的第一个请求包含WebSocket升级头。如果升级头不存在,连接将作为普通的HTTP/1.1连接进行处理。如果升级头存在,Envoy将在客户端和上游服务器之间建立纯TCP代理。因此,如果要拒绝WebSocket升级请求,上游服务器将要负责关闭相关的连接。在关闭连接之前,Envoy将持续从客户端代理数据到上游服务器。

    具有WebSocket升级头的请求不支持重定向,超时和重试。

  • timeout_ms
    (optional, integer) 指定路由的超时时间。如果未指定,则默认值为15秒。请注意,此超时包括所有重试。另请参阅x-envoy-upstream-rq-timeout-msx-envoy-upstream-rq-per-try-timeout-ms重试概述

  • runtime
    (optional, object) 可选,指定路由的运行时配置。

  • retry_policy
    (optional, object) 可选,表示该路由具有重试策略

  • shadow
    (optional, object) 可选,表示路由具有影子策略

  • priority
    (optional, string) 可选,指定路由优先级

  • headers
    (optional, array) 指定与该路由匹配的一组列表。路由器将根据配置中指定头检查请求的头部。如果路由中的所有头都与请求中头的值相同(或者配置中没有指定相应的值,则认定存在),则将发生匹配。

  • request_headers_to_add
    (optional, array) 指定应添加到由此虚拟主机处理的每个请求的HTTP头列表。以下面的形式指定头部:

      [
        {"key": "header1", "value": "value1"},
        {"key": "header2", "value": "value2"}
      ]
    

    有关更多信息,请参阅自定义请求头的文档。

  • opaque_config
    (optional, array) 指定可由过滤器访问的一组可选路由配置值

  • rate_limits
    (optional, array) 指定可应用与该路由的一组速率限制配置

  • include_vh_rate_limits
    (optional, boolean) 指定速率限制过滤器是否应包含虚拟主机的速率限制。默认情况下,如果路由配置的速率限制,虚拟主机rate_limits将不适用于请求。

  • hash_policy
    (optional, object) 如果上游群集使用哈希负载平衡器,则通过此选项指定路由的哈希策略

  • decorator
    (optional, object) 指定用于增强相关匹配的路由描述信息,用于信息上报。

Runtime

可用于路由的运行时配置,开展路由的逐步变更,而无需部署完整的代码/配置。请参阅流量转移文档

{
  "key": "...",
  "default": "..."
}
  • key
    (required, string) 指定运行时应查询的键的名称,以确定路由是否匹配。有关键名称如何映射到底层实现,请参阅运行时文档

  • default
    (required, integer) 一个0-100之间的整数,每当路由匹配时,会选择0-99之间的随机数。若该值<=在该键中找到的值(优先检查),或者若该键不存在,则为默认值,该路由是匹配的(假定所有的都路由匹配)。

Retry policy

HTTP重试架构概述

{
  "retry_on": "...",
  "num_retries": "...",
  "per_try_timeout_ms" : "..."
}
  • retry_on
    (required, string) 指定重试的发生条件。这些是与x-envoy-retry-onx-envoy-retry-grpc-on记录的条件相同。

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

  • per_try_timeout_ms
    (optional, integer) 指定每个重试尝试的非零超时。该参数是可选的。与x-envoy-upstream-rq-per-try-timeout-ms记录的条件相同。

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

Shadow

路由器能够实现将流量从一个集群映射到另一个集群。目前的实现是“fire and forget”,这意味着Envoy在返回来自主集群的响应之前不会等待影子集群作出响应。所有正常的统计数据都会被收集用于阴影集群,使得该功能对测试很有用。

在shadow期间,host/authority头被改变,使得-shadow被附加。这对于日志记录很有用。例如:cluster1变为cluster1-shadow

{
  "cluster": "...",
  "runtime_key": "..."
}
  • cluster
    (required, string) 指定请求将被映射到的群集。群集必须存在于群集管理器配置中。

  • runtime_key
    (optional, string) 如果未指定,则对目标群集的所有请求都将被映射。如果指定,Envoy将查找运行时键,以获取请求的百分比。有效值从0到10000,允许0.01%的增幅。如果运行时键在配置中指定,但运行时不存在,则默认为0,因此请求的0%将被映射。

Headers

{
  "name": "...",
  "value": "...",
  "regex": "..."
}
  • name
    (required, string) 指定请求中头部的名称。

  • value
    (optional, string) 指定头的值。如果值不存在,则具有头名的请求都将匹配,而不管头的值如何。

  • regex
    (optional, boolean) 指定头的值是否采用正则表达式。默认为false。整个请求头的值必须与正则表达式匹配。如果只有请求头值的子序列与正则表达式匹配,则规则不匹配。这里定义了值字段中使用的正则表达式语法

    示例:

    • 正则表达式d{3}匹配123值
    • 正则表达式d{3}不匹配1234值
    • 正则表达式d{3}不匹配123.456值

      注意:在内部,Envoy始终使用HTTP/2的:authority来表示HTTP/1主机头。因此,如果试图匹配主机,则匹配:authority替代。

      注意:若要使用HTTP的method进行路由,请使用特殊的HTTP/2的:method头。这适用于HTTP/1和HTTP/2,因为Envoy标准化头。例如:

      {
      "name": ":method",
      "value": "POST"
      }
      

Weighted Clusters

与指定单个上游群集作为请求的目标群集相比,weighted_clusters选项允许指定多个上游群集,以及指定要转发给每个群集的流量的百分比权重。路由器将根据权重选择上游集群。

{
  "clusters": [],
  "runtime_key_prefix" : "..."
}
  • clusters
    (required, array) 指定与路由器相关的一个或多个上游群集。

      {
        "name" : "...",
        "weight": "..."
      }
    
    • name
      (required, string) 上游群集的名称。群集必须存在于群集管理器配置中。

    • weight
      (required, integer) 一个0-100之间的整数,当请求与路由匹配时,选择上游集群的权重比。集群组中所有权重之和必须为100。

  • runtime_key_prefix
    (optional, string) 指定运行时每个群集相关的运行时键的前缀。当指定runtime_key_prefix时,路由器将在键为runtime_key_prefix + "." + cluster[i].name下查找与每个上游集群相关的权重。其中,cluster[i]表示集群组中的条目。如果群集的运行时键不存在,则配置文件中指定的值将用作默认权重。有关键名称如何映射到底层实现,请参阅运行时文档。

    注意:如果运行时权重之和超过100,则流量拆分的行为将未定义(尽管请求将被路由到其中一个集群)。

Hash policy

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

{
  "header_name": "..."
}
  • header_name
    (required, string) 获取的请求头部的名称作为哈希值。如果请求头不存在,负载均衡器将使用一个随机数作为哈希值,从而使得有效地使负载均衡策略变为随机策略。

Decorator

指定路由的修饰符。

{
  "operation": "..."
}
  • operation
    (required, string) 与此路由匹配的请求相关的操作名称。如果已启用跟踪,则将使用此信息作为为此请求跟踪记录的span名称。注意:对于入口(入站)请求或出口(出站)响应,此值可能会被x-envoy-decorator-operation头部覆盖。

Opaque Config

可以通过“不透明配置”机制为过滤器提供额外的配置。在路由配置中指定属性列表。该配置不能未被Envoy解释,可以在用户定义的过滤器中访问。该配置是一个通用的字符串映射。不支持嵌套对象。

[
  {"...": "..."}
]

Cors

设置路由的优先于虚拟主机的设置。

{
  "enabled": false,
  "allow_origin": ["http://foo.example"],
  "allow_methods": "POST, GET, OPTIONS",
  "allow_headers": "Content-Type",
  "allow_credentials": false,
  "expose_headers": "X-Custom-Header",
  "max_age": "86400"
}
  • enabled
    (optional, boolean) 默认为true。只有在路由上启用并设置为false,才会禁用此路由的CORS。该设置对虚拟主机没有影响。

  • allow_origin
    (optional, array) 将允许做CORS请求的来源。通配符“*”表示允许任何来源。

  • allow_methods
    (optional, string) access-control-allow-methods头的内容。以逗号分隔的HTTP方法列表。

  • allow_headers
    (optional, string) access-control-allow-headers头的内容。以逗号分隔的HTTP标题列表。

  • allow_credentials
    (optional, boolean) 资源是否允许凭证。

  • expose_headers
    (optional, string) access-control-expose-headers头的内容。以逗号分隔的HTTP标题列表。

  • max_age
    (optional, string) access-control-max-age头的内容。以秒为单位的值,可以缓存对预检请求的响应时间。

返回

results matching ""

    No results matching ""