跳过内容

一致性

此 API 涵盖了广泛的功能和用例,并且已在广泛实施。这种功能集大且实现方式多种的组合需要明确的一致性定义和测试,以确保 API 在任何使用它的地方提供一致的体验。

在考虑网关 API 一致性时,有三个重要的概念

1. 发布渠道

在网关 API 中,发布渠道用于指示字段或资源的稳定性。API 的“标准”渠道包括已升级到“beta”的字段和资源。API 的“实验性”渠道包括“标准”渠道中的所有内容,以及可能仍以破坏性方式更改 **或完全删除** 的实验性字段和资源。有关此概念的更多信息,请参阅我们的 版本控制 文档。

2. 支持级别

不幸的是,一些 API 实现将无法支持已定义的每个功能。为了解决这个问题,API 为每个功能定义了相应的支持级别

  • **核心** 功能将是可移植的,我们预计所有实现都将有一个合理的路线图来支持此类 API。
  • **扩展** 功能是指可移植的但并非在所有实现中普遍支持的功能。支持该功能的那些实现将具有相同的行为和语义。预计一些路线图功能最终将迁移到核心。扩展功能将是 API 类型和模式的一部分。
  • **特定于实现** 的功能是指不可移植的、特定于供应商的功能。特定于实现的功能将没有 API 类型和模式,除非通过通用扩展点。

核心和扩展集的行为和功能将通过行为驱动的一致性测试进行定义和验证。特定于实现的功能将不受一致性测试的涵盖。

通过在 API 规范中包含和标准化扩展功能,我们希望能够在实现之间收敛到 API 的可移植子集,而不会影响整体 API 支持。缺乏普遍支持不会成为开发可移植功能集的障碍。标准化规范将使最终在支持广泛的情况下升级到核心变得更加容易。

重叠支持级别

支持级别可能会对特定字段重叠。发生这种情况时,应解释最低表达的支持级别。例如,相同的结构可以嵌入两个不同的位置。在其中一个位置,该结构被认为具有核心支持,而另一个位置只包含扩展支持。此结构中的字段可能会表达单独的核心和扩展支持级别,但这些级别不得解释为超过其嵌入的父结构的支持级别。

对于更具体的示例,HTTPRoute 包括对规则中定义的过滤器的核心支持,以及对 BackendRef 中定义的过滤器的扩展支持。这些过滤器可能会分别为每个字段定义支持级别。在解释重叠支持级别时,应解释最小值。这意味着,如果一个字段具有核心支持级别,但位于扩展支持的位置附加的过滤器中,则解释的支持级别必须是扩展的。

3. 一致性测试

网关 API 包含一组一致性测试。这些测试创建了一系列使用指定 GatewayClass 的网关和路由,并测试实现是否与 API 规范匹配。

每个版本都包含一组一致性测试,这些测试将随着 API 的发展而不断扩展。目前一致性测试涵盖了标准渠道中大多数核心功能,以及一些扩展功能。

运行测试

主要有两组对比鲜明的一致性测试

  • 与网关相关的测试(也可以被认为是入口测试)
  • 与服务网格相关的测试

对于 Gateway 测试,您必须启用 Gateway 测试功能,然后选择加入您想要运行的任何其他特定测试(例如 HTTPRoute)。对于与网格相关的测试,您必须启用 Mesh

我们将分别介绍每种用例,但如果您的实现同时实现了这两种用例,也可以将它们组合起来。还有一些选项适用于整个测试套件,无论您运行的是哪些测试。

网关测试

默认情况下,Gateway 方向的一致性测试将期望在集群中安装名为 gateway-conformance 的 GatewayClass,并且测试将针对该类运行。大多数情况下,您将使用不同的类,它可以使用 -gateway-class 标志以及相应的测试命令来指定。检查您的实例以了解要使用的 gateway-class 名称。您还必须启用 Gateway 支持和对您的实现支持的任何 *Routes 的测试支持。

以下运行所有与 GatewayHTTPRouteReferenceGrant 相关的测试

go test ./conformance -run TestConformance -args \
    --gateway-class=my-gateway-class \
    --supported-features=Gateway,HTTPRoute

其他有用的标志可以在 一致性标志 中找到。

网格测试

只需启用 Mesh 功能即可运行网格测试

go test ./conformance -run TestConformance -args --supported-features=Mesh

如果您的网格还使用 HTTPRoute 等 API 包含入口支持,则可以通过启用 Gateway 功能和任何相关的 API 功能在相同的测试运行中运行相关测试,例如

go test ./conformance -run TestConformance -args --supported-features=Mesh,Gateway,HTTPRoute

命名空间标签和注释

如果测试中使用的命名空间需要标签,则可以使用 -namespace-labels 标志传递一个或多个 name=value 标签以设置在测试命名空间上。同样,-namespace-annotations 可以用来指定要应用于测试命名空间的注释。对于网格测试,如果实现需要托管网格工作负载的命名空间上的标签(例如,启用 sidecar 注入),则可以使用此标志。

例如,在测试 Linkerd 时,您可能会运行

go test ./conformance -run TestConformance -args \
   ...
   --namespace-annotations=linkerd.io/inject=enabled

以便正确将测试命名空间注入网格。

排除测试

GatewayReferenceGrant 功能默认启用。您无需使用 -supported-features 标志显式列出它们。但是,如果您不想运行它们,则需要使用 -exempt-features 标志禁用它们。例如,要仅运行 Mesh 测试,而无需运行其他任何测试

go test ./conformance -run TestConformance -args \
    --supported-features=Mesh \
    --exempt-features=Gateway,ReferenceGrant

套件级别选项

在运行任何类型的测试时,您可能不希望测试套件在完成时清理测试资源(例如,以便您可以在发生故障时检查集群状态)。您可以通过设置 --cleanup-base-resources=false 标志来跳过清理。

通过名称运行非常具体的测试可能很有帮助(尤其是在实现特定功能时)。这可以通过设置 --run-test 标志来完成。

网络策略

在使用 容器网络接口 (CNI) 插件 强制实施网络策略的集群中,某些一致性测试可能需要自定义 NetworkPolicy 资源被添加到集群中,以便允许流量到达所需的目的地。

预计用户将添加这些所需的网络策略,以便他们的实现通过这些测试。

一致性配置文件

一致性配置文件是将多个支持的功能分组在一起的工具,其目标是通过一致性报告来认证其支持。支持的配置文件可以使用 --conformance-profiles=PROFILE1,PROFILE2 标志进行配置。

一致性报告

如果套件已配置为运行一组一致性配置文件,并且所有一致性报告字段都已根据 本指南 正确设置,则可以通过 PR 将一致性报告上传到 此文件夹 中。遵循 本指南,详细了解如何构建和提交特定实现的报告。

为一致性做贡献

许多实现将一致性测试作为其完整 e2e 测试套件的一部分运行。贡献一致性测试意味着实现可以共享测试开发的投资,并确保我们提供一致的体验。

与一致性相关的所有代码都位于项目的“/conformance”目录中。测试定义位于“/conformance/tests”中,每个测试都包含一对文件。YAML 文件包含要作为运行测试的一部分应用的清单。Go 文件包含确认实现适当地处理这些清单的代码。

与一致性相关的 issue 带有“area/conformance”标签。这些通常涵盖添加新的测试以改进我们的测试覆盖率或修复我们现有测试中的缺陷或限制。