路由表检查工具

注意

以下配置仅用于路由表检查工具，不是 Envoy 二进制文件的一部分。路由表检查工具是一个独立的二进制文件，可用于验证 Envoy 对给定配置文件的路由。

以下指定了路由表检查工具的输入。路由表检查工具检查由路由器返回的路由是否符合预期。该工具可用于检查集群名称、虚拟集群名称、虚拟主机名称、手动路径重写、手动主机重写、路径重定向和标头字段匹配。可以为其他测试用例添加扩展。有关安装工具和示例工具输入/输出的详细信息，请参见安装。

路由表检查工具配置由一个 json 测试对象数组组成。每个测试对象由三个部分组成。

测试名称: 此字段指定每个测试对象的名称。
输入值: 输入值字段指定要传递给路由器的参数。示例输入字段包括：authority、:path 和 :method 标头字段。:authority 和 :path 字段指定发送到路由器的 url，并且是必需的。所有其他输入字段都是可选的。
验证: validate 字段指定预期值和要检查的测试用例。至少需要一个测试用例。

一个简单的工具配置 json 具有一个测试用例，如下所示。该测试期望集群名称匹配为“instant-server”。

tests
- test_name: Cluster_name_test
  input:
    authority: api.lyft.com
    path: /api/locations
  validate:
    cluster_name: instant-server

tests
- test_name: ...
  input:
    authority: ...
    path: ...
    method: ...
    internal: ...
    random_value: ...
    ssl: ...
    runtime: ...
    additional_request_headers:
      - key: ...
        value: ...
    additional_response_headers:
      - key: ...
        value: ...
  validate:
    cluster_name: ...
    virtual_cluster_name: ...
    virtual_host_name: ...
    host_rewrite: ...
    path_rewrite: ...
    path_redirect: ...
    request_header_matches:
      - name: ...
        string_match:
          exact: ...
    response_header_matches:
      - name: ...
        string_match:
          exact: ...
      - name: ...
        presence_match: ...

test_name

(必需，字符串) 测试对象的名称。

input

(必需，对象) 发送到路由器的输入值，这些值决定返回的路由。

authority

(必需，字符串) url 授权。此值与 path 参数一起定义要匹配的 url。示例授权值为“api.lyft.com”。

path

(必需，字符串) url 路径。示例路径值为“/foo”。

method

(必需，字符串) 请求方法。如果未指定，则默认方法为 GET。

internal

(可选，布尔值) 一个标志，用于确定是否将 x-envoy-internal 设置为“true”。如果未指定，或者如果 internal 等于 false，则不会设置 x-envoy-internal。

random_value

(可选，整数) 用于标识加权集群选择的目标以及作为路由引擎决定是否应使用基于运行时的路由的因素的整数。random_value 的默认值为 0。对于运行时分数分子为 0 的路由，路由检查器工具将分子更改为 1，以便可以使用设置为 0 的 random_value 来测试它们，以模拟路由已启用，并将 random_value 设置为任何 int >= 1 以模拟路由已禁用。

ssl

(可选，布尔值) 一个标志，用于确定是否将 x-forwarded-proto 设置为 https 或 http。通过将 x-forwarded-proto 设置为给定协议，该工具能够模拟客户端通过 http 或 https 发出请求的行为。默认情况下，ssl 为 false，对应于 x-forwarded-proto 设置为 http。

runtime

(可选，字符串) 表示要为测试启用的运行时设置的字符串。运行时设置与 random_value 一起由路由器用来决定是否应启用路由。只有小于路由条目中定义的分数百分比的 random_value 才会启用路由。

additional_request_headers, additional_response_headers

(可选，数组) 要添加为路由确定的输入的附加标头。“authority”、“path”、“method”、“x-forwarded-proto”和“x-envoy-internal”字段由其他配置选项指定，不应在此处设置。

key: (必需，字符串) 要添加的标头字段的名称。
value: (必需，字符串) 要添加的标头字段的值。

validate

(必需，对象) validate 对象指定要匹配的返回路由参数。必须指定至少一个测试参数。使用“” (空字符串) 表示不希望返回值。例如，要测试是否不希望集群匹配，请使用 {“cluster_name”: “”}。

cluster_name

(可选，字符串) 匹配集群名称。

virtual_cluster_name

(可选，字符串) 匹配虚拟集群名称。

virtual_host_name

(可选，字符串) 匹配虚拟主机名称。

host_rewrite

(可选，字符串) 匹配重写后的主机标头字段。

path_rewrite

(可选，字符串) 匹配重写后的路径标头字段。

path_redirect

(可选，字符串) 匹配返回的重定向路径。

code_redirect

(可选，整数) 匹配重定向响应代码。

request_header_fields, response_header_fields

(可选，数组，已弃用) 匹配列出的标头字段。示例标头字段包括“path”、“cookie”和“date”字段。标头字段在所有其他测试用例之后检查。因此，检查的标头字段将是重定向或重写的路由的标头字段（如果适用）。这些字段已弃用。请改用 request_header_matches、response_header_matches。

key: (必需，字符串) 要匹配的标头字段的名称。
value: (必需，字符串) 要匹配的标头字段的值。

request_header_matches, response_header_matches

(可选，数组) 列出标头的匹配器。示例标头字段包括“path”、“cookie”和“date”字段，以及在输入中或由路由设置的自定义标头。标头字段在所有其他测试用例之后检查。因此，检查的标头字段将是重定向或重写的路由的标头字段（如果适用）。 - 匹配器指定为 HeaderMatchers，并且行为相同。

覆盖范围

路由检查工具将在成功测试运行结束后报告路由覆盖率。

> bazel-bin/test/tools/router_check/router_check_tool --config-path ... --test-path ...
Current route coverage: 0.0744863

此报告可以通过使用 -f 或 --fail-under 标志来利用，以强制执行最低覆盖率百分比。如果覆盖率低于此百分比，则测试运行将失败。

> bazel-bin/test/tools/router_check/router_check_tool --config-path ... --test-path ... --fail-under 8
Current route coverage: 7.44863%
Failed to meet coverage requirement: 8%

默认情况下，覆盖率报告通过检查每个路由是否至少验证了一个字段来衡量测试覆盖率。但是，这可能会导致测试中存在漏洞，其中字段未经验证，并在以后更改。为了获得更全面的覆盖率，您可以添加一个标志 --covall，它将计算覆盖率，同时考虑所有可能测试的字段。

> bazel-bin/test/tools/router_check/router_check_tool --config-path ... --test-path ... --f 7 --covall
Current route coverage: 6.2948%
Failed to meet coverage requirement: 7%