聚焦 SIG Architecture：API 治理

这是 SIG Architecture 聚焦系列的第五次访谈，该系列涵盖不同的子项目，本次我们将介绍 SIG Architecture：API Governance。

在本期 SIG Architecture 聚焦中，我们采访了 API Governance 子项目负责人 Jordan Liggitt。

介绍

FM：你好，Jordan，感谢你抽出时间。请向我们简单介绍一下你自己、你的角色，以及你是如何参与 Kubernetes 的。

JL：我叫 Jordan Liggitt。我是一名基督徒、丈夫、四个孩子的父亲，白天是 Google 的软件工程师，私下里还是一名业余音乐人。我出生在 Texas（并且仍然喜欢把它称为我的起点），但我人生中的大部分时间都住在 North Carolina。

我从 2014 年开始参与 Kubernetes。当时，我在 Red Hat 从事认证和授权方面的工作，而我向 Kubernetes 提交的第一个 pull request，试图向 Kubernetes API server 添加一个 OAuth server。它从未脱离 work-in-progress 状态。后来我采用了另一种方法，在另一个项目中叠加在核心 Kubernetes API server 之上（剧透提醒：这是伏笔），并在六个月后关闭了它，没有合并。

尽管一开始如此，我并没有气馁，而是继续参与其中，帮助构建 Kubernetes 的认证和授权能力，并参与了核心 Kubernetes API 从早期 beta API（如 v1beta3）到 v1 的定义和演进。基于这些贡献，我在 2016 年被标记为 API reviewer，并在 2017 年被添加为 API approver。

如今，我协助领导 SIG Architecture 下的 API Governance 和代码组织子项目，同时也是 SIG Auth 的技术负责人。

FM：你具体是什么时候参与到 API Governance 项目中的？

JL：大约在 2019 年。

API Governance 的目标和范围

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

表面积包括 Kubernetes 所拥有的各种 API，其中有些 API 人们并不总是意识到它们是 API：命令行标志、配置文件、二进制文件的运行方式、它们如何与容器运行时等后端组件通信，以及它们如何持久化数据。人们通常认为“API”仅指 REST API……这是最大、最明显的一个，也是受众最广的一个，但所有这些其他表面同样也是 API。它们的受众更窄，因此在这些方面有更大的灵活性，但仍然需要加以考虑。

目标是在保持稳定的同时仍然支持创新。如果你从不改变任何东西，稳定很容易实现，但这与演进和增长的目标相矛盾。因此，我们在“保持稳定”和“允许变更”之间取得平衡。

FM：说到变更，就确保一致性和质量而言（这显然是这个项目存在的原因之一），Kubernetes 变更生命周期中具体的质量关卡有哪些？API Governance 是在发布周期中介入，还是在发布之前通过指南介入，抑或是在两者之间的某个阶段介入？你们在什么节点确保其预期作用得以实现？

JL：我们有指南和约定，既适用于一般的 API，也适用于如何更改 API。这些都是动态文档，我们会在遇到新场景时进行更新。它们篇幅较长且内容密集，因此我们也会通过在设计阶段或实现阶段的参与来提供支持。

有时，由于带宽限制，团队会在没有 API Review 反馈的情况下推进设计工作。这没问题，但这意味着当实现开始时，API 审查将在那时进行，并且可能会有大量反馈。因此，当创建新的 API 或更改现有 API 时，我们会在设计阶段或实现阶段介入。

FM：这是在 Kubernetes Enhancement Proposal（KEP）流程期间进行的吗？既然增强功能必须有 KEP，我认为其中一部分工作会与 API Governance 相交？

JL：可能会。KEP 的详细程度各不相同。有些包含字面意义上的 API 定义。当它们包含这些内容时，我们可以在设计阶段进行 API 审查。随后，实现就变成了检查其是否忠实于设计的问题。

尽早参与是理想的。但有些 KEP 仍处于概念阶段，会把细节留给实现来处理。这并没有错；这只是意味着实现会更具探索性。随后 API Review 会在较后阶段介入，可能会建议进行结构性调整。

无论如何都存在一种权衡：是在前期进行详细设计，还是在实现过程中迭代式地探索发现。不同的人和团队有不同的工作方式，我们很灵活，也很乐意在早期或实现阶段提供咨询。

FM：这让我想起 Fred Brooks 在《The Mythical Man-Month》中所写的内容，即概念完整性是产品质量的核心……无论你如何构建流程，都必须有一个环节，由某个人审视即将到来的内容，并确保概念完整性。Kubernetes 在外部和内部都广泛使用 API，因此 API Governance 对于维护这种完整性至关重要。这是如何体现的？

JL：是的，约定文档记录了我们随着时间推移总结出的模式：在各种情况下应该怎么做。我们还拥有自动化的 linter 和检查工具，以确保围绕 spec/status 语义等模式的正确性。即使人工遗漏了问题，这些自动化工具也有助于捕捉问题。

随着新场景不断出现——而它们确实一直在出现——我们会思考如何处理这些场景，并将结果反馈到我们的文档和工具中。有时需要尝试几次，才能确定一种行之有效的方法。

FM：确实如此。每一次新的互动都会完善这些指南。

JL：没错。而且有时最初的方法后来被证明是错误的。可能需要两三轮迭代，我们才能找到一个稳健的方案。

Custom Resource Definitions 的影响

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

JL：分水岭时刻是 Custom Resources。在此之前，每个 API 都由我们手工打造并经过全面审查。虽然存在不一致之处，但我们理解并控制着每一种类型和字段。

Custom Resources 出现后，任何人都可以定义任何东西。第一个版本甚至不要求 schema。这使它极其强大——能够立即促成变化——但也让我们在稳定性和一致性方面不断追赶。

当 Custom Resources 升级为 General Availability（GA）时，schema 变成了必需项，但出于向后兼容性考虑，仍然存在一些逃生通道。从那时起，我们一直在努力为 CRD 作者提供可与内置资源相媲美的验证能力。用于 CRD 的内置验证规则直到最近几个版本才刚刚达到 GA。

因此，CRD 开启了“万事皆有可能”的时代。内置验证规则是第二个重要里程碑：让一致性回归。

三大主题一直是定义模式、验证数据以及处理既有的无效数据。借助渐进式验证（允许数据在不破坏现有对象的情况下得到改进），我们现在可以引导 CRD 作者遵循约定，而不会破坏整个生态。

API 治理的背景

FM：API 治理与 SIG Architecture 和 API Machinery 有什么关系？

JL：API Machinery 提供人们用来构建 API 的实际代码和工具。他们不负责审查存储、网络、调度等方面的 API。

SIG Architecture 设定整体系统方向，并与 API Machinery 合作，确保系统支持这一方向。API Governance 与基于该基础进行构建的其他 SIG 合作，定义约定和模式，确保一致地使用 API Machinery 所提供的内容。

FM：谢谢。这理清了流程。回到发布周期：发布阶段——增强功能冻结、代码冻结——会改变你们的工作量吗？还是 API Governance 的工作基本上是持续进行的？

JL：我们在两个环节参与：设计和实现。在增强功能冻结之前，设计方面的参与会增加；在代码冻结之前，实现方面的参与会增加。不过，许多工作会跨越多个发布版本，因此始终会有一些设计和实现工作在进行，即使是面向未来版本的工作也是如此。在这些紧张时期之间，我们通常有时间从事长期设计工作。

我们看到的一种反模式是，团队花几个月思考一个大型功能，然后在增强功能冻结前三周拿出来说：“这是设计，请审查。”对于会影响 API 的重大变更，尽早让 API Governance 参与进来要好得多。

而且在周期中也有适合这样做的好时机——也就是两次冻结之间——这时人们有余力。长期审查工作最适合安排在这个时候。

参与进来

FM：很清楚。那么，关于团队动态和新贡献者：有人如何参与 API Governance？他们应该关注什么？

JL：通常最好是关注某个具体变更，而不是试图一次性学会所有东西。选择一个小的 API 变更，可能是别人正在做的，也可能是你想做的，然后观察完整流程：设计、实现、评审。

高带宽评审——通过视频进行实时讨论——通常非常有效。如果你正在做或关注某个变更，可以询问是否有时间一起讨论设计或 PR。旁听这些讨论极具启发性。

从一个小变更开始。然后再推进到更大的变更。之后也许是一个新的 API。这样可以在约定被实际应用的过程中逐步建立理解。

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

JL：是的……我们之所以如此重视兼容性和稳定性，是为了我们的用户。贡献者很容易把这些要求看作是令人痛苦的障碍，阻碍清理工作，或要求繁琐的劳动……但用户已经与我们的系统集成，而我们也向他们作出了承诺：我们希望他们相信，我们不会破坏这份约定。因此，即使这需要更多工作、进展更慢，或涉及重复，我们也会选择稳定性。

我们并不是想设置障碍；我们是在努力让用户过得更好。

我们的很多问题都着眼于未来：你现在想做某件事……以后要如何在不破坏它的情况下演进？我们假设未来会知道得更多，并希望设计能为此留出空间。

我们也假设自己会犯错。那么问题就是：在遵守兼容性承诺的同时，我们如何给自己留下改进的途径？

FM：没错。Jordan，谢谢你，我想我们已经涵盖了所有内容。这让我们深入了解了 API Governance 项目及其在更广泛的 Kubernetes 项目中的作用。

JL：谢谢。

• ← 上一篇
• 下一篇 →