Kubernetes 1.27：服务端字段验证和 OpenAPI V3 升级至 GA

在 Kubernetes v1.8 之前 (!)，YAML 中的拼写错误、缩进错误或小错误可能会导致灾难性的后果（例如，像在 replica: 1000 中忘记尾随的 s 这样的拼写错误可能会导致中断，因为该值将被忽略并丢失，从而强制将副本重置为 1）。当时，通过在 kubectl 中获取 OpenAPI v2 并使用它来验证字段是否正确且存在来解决这个问题。不幸的是，当时不存在自定义资源定义 (CRD)，并且代码是在这种假设下编写的。当后来引入 CRD 时，验证代码缺乏灵活性迫使我们在 CRD 公开其架构的方式上做出一些艰难的决定，使我们陷入糟糕的验证导致糟糕的 OpenAPI，反之亦然的循环。随着新的 OpenAPI v3 和服务器端字段验证在 1.27 中正式发布，我们现在已经解决了这两个问题。

服务器端字段验证在对 apiserver 的创建、更新和修补请求时提供资源验证，并在 v1.25 中添加到 Kubernetes，在 v1.26 中处于 beta 阶段，现在在 v1.27 中正式发布。它在服务器端提供了 kubectl 验证的所有功能。

OpenAPI 是一个标准的、与语言无关的接口，用于发现 Kubernetes 集群支持的操作和类型集合。OpenAPI V3 是 OpenAPI 的最新标准，并且是对自 Kubernetes 1.5 以来支持的 OpenAPI V2 的改进。OpenAPI V3 支持在 Kubernetes v1.23 中添加，在 v1.24 中进入 beta 阶段，现在在 v1.27 中正式发布。

OpenAPI V3

OpenAPI V3 相对于 V2 提供什么

内置类型

Kubernetes 在字段上提供某些在 OpenAPI V2 中不可表示的注释，或者有时在 Kubernetes 生成的 OpenAPI v2 中不表示的注释。最值得注意的是，“default”字段在 OpenAPI V3 中发布，而在 OpenAPI V2 中省略。可以使用 oneOf 字段在 OpenAPI V3 中正确表达可以表示多种类型的单个类型。这包括 IntOrString 和 Quantity 的正确表示。

自定义资源定义

在 Kubernetes 中，自定义资源定义使用结构化的 OpenAPI V3 架构，该架构不能在不丢失某些字段的情况下表示为 OpenAPI V2。其中一些包括 nullable、default、anyOf、oneOf、not 等。OpenAPI V3 是 CustomResourceDefinition 结构化架构的完全无损表示。

如何使用它？

OpenAPI V3 根发现可以在 Kubernetes API 服务器的 /openapi/v3 端点找到。OpenAPI V3 文档按组版本分组以减少传输的数据量，可以在 /openapi/v3/apis/<group>/<version> 和表示旧版组版本的 /openapi/v3/api/v1 访问单独的文档。请参阅Kubernetes API 文档以获取有关此端点的更多信息。

OpenAPI 的各种使用者已更新为使用 v3，包括整个 kubectl 和服务器端应用。OpenAPI V3 Golang 客户端可在 client-go 中找到。

服务器端字段验证

查询参数 fieldValidation 可用于指示服务器应执行的字段验证级别。如果未传递参数，则服务器端字段验证默认处于 Warn 模式。

• Strict: 严格字段验证，验证失败时会出错
• Warn: 执行字段验证，但错误以警告的形式公开，而不是使请求失败
• Ignore: 不执行服务器端字段验证

kubectl 将跳过客户端验证，并将自动在 Strict 模式下使用服务器端字段验证。控制器默认在 Warn 模式下使用服务器端字段验证。

对于客户端验证，我们必须格外宽松，因为 OpenAPI V2 中缺少某些字段，并且我们不想拒绝可能有效的对象。这在服务器端验证中都已修复。其他文档可在此处找到这里

下一步是什么？

随着服务器端字段验证和 OpenAPI V3 作为 GA 发布，我们引入了 Kubernetes 资源的更准确表示。建议使用服务器端字段验证而不是客户端，但使用 OpenAPI V3，如果需要（“将事情提前”），客户端可以自由实施自己的验证，并且我们保证由 OpenAPI 发布完整的无损架构。

一些现有的工作将进一步改进通过 OpenAPI 提供的可用信息，包括 CEL 验证和准入，以及内置类型的 OpenAPI 注释。

可以使用 OpenAPI v3 中找到的类型信息来构建许多其他用于创作和转换资源的工具。

如何参与？

这两个功能由 SIG API Machinery 社区推动，可在 Slack 频道 #sig-api-machinery 上获得，通过 邮件列表，我们每隔一个星期三太平洋时间上午 11:00 在 Zoom 上开会。

我们非常感谢所有帮助设计、实施和审查这两个功能的贡献者。

• Alexander Zielenski
• Antoine Pelisse
• Daniel Smith
• David Eads
• Jeffrey Ying
• Jordan Liggitt
• Kevin Delgado
• Sean Sullivan

• ←上一篇
下一篇→