跳至内容

API 设计指南

在本 API 中使用了一些通用的设计指南。

注意

在整个网关 API 文档和规范中,广泛使用了“必须”、“可以”和“应该”等关键词。这些应该按照 RFC 2119 中的描述进行解释。

单资源一致性

Kubernetes API 仅保证单资源级别的 一致性。与单个资源相比,对于复杂资源图,存在以下几个后果

  • 跨越多个资源的属性错误检查将是异步的,并且最终一致的。在单资源级别可以进行简单的语法检查,但控制器需要处理跨资源依赖关系。
  • 控制器需要处理资源之间的断开链接和/或配置不匹配。

冲突

独立参与者(例如集群运营和应用程序开发人员)之间的职责分离和委托会导致配置冲突。例如,两个应用程序团队可能会无意中为相同的 HTTP 路径提交配置。

在大多数情况下,冲突解决的指南将与可能出现冲突的字段的文档一起提供。如果冲突没有规定的解决方案,则应应用以下指导原则

  • 优先不破坏正在运行的事物。
  • 尽可能少地丢弃流量。
  • 在发生冲突时提供一致的体验。
  • 当发现冲突时,应明确哪个路径已被选择。在可能的情况下,这应该通过在相关资源上设置适当的状态条件来传达。
  • 更具体的匹配应该优先于不太具体的匹配。
  • 具有最旧创建时间戳的资源获胜。
  • 如果其他所有内容都相同(包括创建时间戳),则应优先考虑按字母顺序(命名空间/名称)先出现的资源。例如,foo/bar 将优先于 foo/baz。

优雅地处理未来的 API 版本

在实施本 API 时,一个重要的考虑因素是它在将来如何改变。与之前的 Ingress API 类似,本 API 被设计为可以在同一个集群中由各种不同的产品来实现。这意味着您的实现开发的 API 版本可能与它使用的 API 版本不同。

为了确保 API 的未来版本不会破坏您的实现,至少必须满足以下要求

  • 处理验证放松的字段而不会崩溃
  • 处理从必需转换为可选的字段而不会崩溃

支持的 API 版本

可以通过查看每个 CRD 上的 gateway.networking.k8s.io/bundle-version 注释来确定集群中安装的网关 API CRD 的版本。每个实现必须将其与它识别和支持的版本列表进行比较。具有 GatewayClass 的实现必须在 GatewayClass 上发布 SupportedVersion 条件,以指示集群中安装的 CRD 是否受支持。

CRD 和 Webhook 验证的限制

Webhook 验证已弃用

网关 API 中的 Webhook 验证已弃用,并在 v1.1.0 中完全删除。也就是说,只要实现支持 v1.0.0 或更早版本的 API,所有这些指导都将继续适用于实现。

CRD 和 Webhook 验证不是最终验证,即 Webhook 是“不错的 UX”,但不是模式强制执行。此验证旨在在用户提供无效配置时提供即时反馈。防御性地编写代码,假设至少一些无效输入(网关 API 资源)将到达您的控制器。Webhook 和 CRD 验证都不是完全可靠的,因为它们

  • 可能没有正确部署。
  • 在将来的 API 版本中可能会放松。(在 API 的较新版本中,字段可能包含具有更少限制性验证的值)。

注意:这些限制并非网关 API 独有,更广泛地适用于任何 Kubernetes CRD 和 Webhook。

实现者应确保,即使遇到 API 中的意外值,其实现也应尽可能安全,并优雅地处理此输入。最常见的响应是将配置拒绝为格式错误,并通过状态块中的条件向用户发出信号。为了避免重复工作,网关 API 维护者正在考虑添加一个共享验证包,实现可以使用该包来实现此目的。这是由 #926 跟踪的。

预期

我们预计在该 API 的早期阶段,不同提供商之间的一致性程度会有所不同。用户可以使用一致性测试的结果来了解行为可能与规范不同的领域。

特定于实现的

在 API 的某些方面,我们赋予用户指定使用功能的能力,但是,确切的行为可能取决于底层实现。例如,正则表达式匹配存在于所有实现中,但由于使用底层库(例如 PCRE、ECMA、Re2)之间的细微差异,无法指定确切的行为。为用户尽可能详细地指定功能仍然是有用的,但我们承认,API 的某些子集的行为可能仍然会有所不同(这是可以的)。

这些情况将被指定为定义 API“特定于实现”的界定部分。

Kind 与资源

与其他 Kubernetes API 类似,网关 API 在整个 API 中使用“Kind”而不是“Resource”。这种模式对于大多数 Kubernetes 用户来说应该很熟悉。

根据 Kubernetes API 约定,这意味着该 API 的所有实现都应该在 kind 和资源之间具有预定义的映射。依赖动态资源映射是不安全的。

API 约定

网关 API 遵循 Kubernetes API 的 约定。这些约定旨在简化客户端开发并确保配置机制能够在各种用例中始终如一地实现。除了 Kubernetes API 约定之外,网关 API 还具有以下约定

列表名称

此项目使用的另一个约定是为 CRD 中的列表使用复数字段名。我们使用以下规则

  • 如果字段名是名词,则使用复数形式。
  • 如果字段名是动词,则使用单数形式。