聚焦 SIG Architecture：API 治理

原文链接：https://kubernetes.io/blog/2026/02/12/sig-architecture-api-spotlight/

这是 SIG Architecture Spotlight 系列第五篇访谈，涵盖不同的子项目，本期我们将介绍 SIG Architecture：API 治理（API Governance）。在本期 SIG Architecture 聚焦中，我们采访了 Jordan Liggitt，API 治理子项目的负责人。

引言

FM：Jordan 你好，感谢你接受采访。请介绍一下你自己、你的角色以及你是如何参与 Kubernetes 的。

JL：我叫 Jordan Liggitt。我是一名基督徒、丈夫、四个孩子的父亲，白天是 Google 的软件工程师，私下里是一名业余音乐人。我出生在德克萨斯州（至今仍喜欢称那里是我的故乡），但大部分时间生活在北卡罗来纳州。我从 2014 年开始参与 Kubernetes 工作。当时我在 Red Hat 从事身份认证和授权方面的工作，我向 Kubernetes 提交的第一个 Pull Request 试图向 Kubernetes API 服务器添加 OAuth 服务器。它从未脱离“进行中”状态。最终我采用了另一种方法，在另一个项目中将其作为核心 Kubernetes API 服务器之上的分层实现（剧透：这是伏笔），六个月后我关闭了它，没有合并。尽管开局不利，我仍然坚持参与，帮助构建了 Kubernetes 的身份认证和授权能力，并参与了核心 Kubernetes API 的定义和演进，从早期的 Beta API（如 v1beta3）到 v1。基于这些贡献，我在 2016 年被标记为 API 审查者（API reviewer），并在 2017 年被添加为 API 批准者（API approver）。如今，我帮助领导 SIG Architecture 的 API 治理和代码组织子项目，同时也是 SIG Auth 的技术负责人。

FM：那么你具体是什么时候开始参与 API 治理项目的？

JL：大约在 2019 年。

API 治理的目标与范围

FM：你如何描述该子项目的主要目标和干预领域？

JL：其表面区域包括 Kubernetes 拥有的所有各种 API，而有些 API 人们并不总是意识到它们是 API：命令行标志、配置文件、二进制文件的运行方式、它们如何与后端组件（如容器运行时）通信，以及它们如何持久化数据。人们通常认为“API”仅指 REST API……这是最大、最明显的 API，也是受众最广的 API，但所有这些其他表面也都是 API。它们的受众更窄，因此灵活性更大，但仍然需要加以考虑。目标是保持稳定，同时仍能促进创新。如果你从不改变任何东西，稳定性很容易实现，但这与演进和增长的目标相矛盾。因此，我们在“保持稳定”和“允许变化”之间寻求平衡。

FM：说到变化，在确保一致性和质量方面（这显然是该项目存在的原因之一），Kubernetes 变更生命周期中有哪些具体的质量关卡？API 治理是在发布周期中、通过发布前的指南，还是介于两者之间介入？你在哪些节点确保其预期角色得到履行？

JL：我们有指南和约定，既针对通用 API，也针对如何变更 API。这些是活的文档，我们在遇到新场景时会进行更新。它们篇幅长且内容密集，因此我们还会在设计阶段或实现阶段通过参与来提供支持。有时，由于带宽限制，团队会在没有 API 审查（API Review）反馈的情况下推进设计工作。这没问题，但这意味着当实现开始时，API 审查将在那时进行，并且可能会有大量反馈。因此，当创建新 API 或变更现有 API 时，我们会在设计或实现阶段介入。

FM：这是在 Kubernetes 增强提案（Kubernetes Enhancement Proposal，KEP）流程中进行的吗？由于增强功能必须提交 KEP，我假设部分工作与 API 治理有交集？

JL：有可能。KEP 的详细程度各不相同。有些包含字面的 API 定义。当包含时，我们可以在设计阶段进行 API 审查。然后实现就变成了检查与设计一致性的问题。尽早介入是理想的。但有些 KEP 是概念性的，将细节留给实现。这并没有错；只是意味着实现将更具探索性。然后 API 审查会在后期介入，可能建议进行结构性更改。无论如何都存在权衡：是提前进行详细设计，还是在实现过程中迭代发现。人和团队的工作方式不同，我们很灵活，乐于在设计阶段或实现阶段提供咨询。

FM：这让我想起了 Fred Brooks 在《人月神话》中写到的，概念完整性是产品质量的核心……无论你如何组织流程，都必须有一个节点，有人审视即将产出的内容并确保概念完整性。Kubernetes 在外部和内部都广泛使用 API，因此 API 治理对于维护这种完整性至关重要。这一点是如何体现的？

JL：是的，约定文档记录了我们在长期实践中积累的模式：在各种情况下该怎么做。我们还有自动化的 linter 和检查，以确保围绕 spec/status 语义等模式的正确性。这些自动化工具即使在人类遗漏时也能帮助发现问题。随着新场景的出现——而且这种情况不断发生——我们会思考如何处理它们，并将结果反馈到我们的文档和工具中。有时需要尝试几次才能确定一个行之有效的方法。

FM：正是如此。每一次新的交互都会改进指南。

JL：对。而且有时第一个方法后来被证明是错误的。可能需要两到三次迭代才能找到一个稳健的方案。

自定义资源定义的影响

FM：在你的经验中，是否有某个特定的变化、事件或领域特别值得注意、复杂或有趣？

JL：分水岭时刻是自定义资源（Custom Resources）。在此之前，每个 API 都是由我们手工制作并经过全面审查的。虽然存在不一致之处，但我们理解并控制着每个类型和字段。当自定义资源出现时，任何人都可以定义任何东西。第一个版本甚至不需要 schema。这使得它极其强大——它立即实现了变更——但也让我们在稳定性和一致性方面处于追赶状态。当自定义资源毕业到正式发布（General Availability，GA）时，schema 成为必需，但为了向后兼容，仍然存在逃生舱口。从那时起，我们一直在努力为 CRD 作者提供与内置资源相当的验证能力。CRD 的内置验证规则（Built-in validation rules）直到最近几个版本才达到 GA。因此，CRD 开启了“一切皆有可能”的时代。内置验证规则是第二个重要里程碑：将一致性带回来。三个主要主题一直是：定义 schema、验证数据以及处理预先存在的无效数据。通过棘轮式验证（ratcheting validation，允许数据改进而不破坏现有对象），我们现在可以引导 CRD 作者遵循约定，而不会破坏现有世界。

API 治理的上下文

FM：API 治理与 SIG Architecture 和 API Machinery 的关系如何？

JL：API Machinery 提供人们构建 API 的实际代码和工具。他们不审查存储、网络、调度等方面的 API。SIG Architecture 设定整体系统方向，并与 API Machinery 合作，确保系统支持该方向。API 治理则与在该基础上构建的其他 SIG 合作，定义约定和模式，确保一致地使用 API Machinery 提供的内容。

FM：谢谢。这澄清了流程。回到发布周期：发布阶段——增强功能冻结、代码冻结——是否会改变你的工作量？还是说 API 治理主要是持续性的？

JL：我们在两个地方介入：设计和实现。设计介入在增强功能冻结前增加；实现介入在代码冻结前增加。然而，许多工作跨越多个发布周期，因此即使对于针对未来版本的工作，也始终有一些设计和实现在进行。在这些紧张时期之间，我们通常有时间进行长期设计工作。我们看到的一个反模式是，团队花数月时间思考一个大型功能，然后在增强功能冻结前三周才提出：“这是设计，请审查。”对于具有 API 影响的大型变更，最好尽早让 API 治理介入。而在周期中有很好的时机——在冻结之间——那时人们有带宽。这正是长期审查工作最适合的时候。

如何参与

FM：明白了。现在，关于团队动态和新贡献者：人们如何参与 API 治理？他们应该关注什么？

JL：通常最好是跟随一个具体的变更，而不是试图一次性学习所有内容。选择一个小的 API 变更，可能是别人正在做的，也可能是你自己想做的，然后观察整个过程：设计、实现、审查。高带宽的审查——通过视频进行实时讨论——通常非常有效。如果你正在做或跟随一个变更，可以询问是否有时间一起过一遍设计或 PR。观察这些讨论非常有启发性。从一个小的变更开始。然后转向更大的变更。然后可能是新的 API。这样可以在实践中建立对约定的理解。

FM：很好。还有什么最后的评论，或者我们遗漏了什么吗？

JL：是的……我们如此关心兼容性和稳定性的原因是为了我们的用户。贡献者很容易将这些要求视为痛苦的障碍，阻碍清理工作或需要繁琐的工作……但用户已经与我们的系统集成，我们向他们做出了承诺：我们希望他们相信我们不会破坏那个契约。因此，即使需要更多工作、进展更慢或涉及重复，我们也会选择稳定性。我们不是要故意阻碍；我们是想让用户的生活更美好。我们的许多问题都聚焦于未来：你现在想做什么……将来如何在不破坏它的前提下演进它？我们假设未来我们会知道得更多，我们希望设计为此留出空间。我们还假设我们会犯错。那么问题就是：我们如何为自己留下改进的途径，同时保持兼容性承诺？

FM：正是如此。Jordan，谢谢你，我想我们已经涵盖了所有内容。这让我们对 API 治理项目及其在更广泛的 Kubernetes 项目中的角色有了深刻的了解。

JL：谢谢。