Kubernetes 弃用策略

本文档详细说明了系统各个方面的弃用策略。

Kubernetes 是一个大型系统，包含许多组件和许多贡献者。与任何此类软件一样，功能集会随着时间的推移自然演变，有时可能需要移除某个功能。这可能包括 API、标志甚至整个功能。为了避免破坏现有用户，Kubernetes 对系统中计划移除的方面遵循弃用策略。

弃用 API 的部分内容

由于 Kubernetes 是一个 API 驱动的系统，API 随着时间的推移不断演进，以反映对问题空间的不断深入理解。Kubernetes API 实际上是一组 API，称为“API 组”，每个 API 组独立版本化。API 版本分为 3 个主要级别，每个级别都有不同的弃用策略：

给定版本的 Kubernetes 可以支持任意数量的 API 组以及每个 API 组的任意数量版本。

以下规则管理 API 元素的弃用。这包括

• REST 资源（又称 API 对象）
• REST 资源的字段
• REST 资源上的注解，包括 "beta" 注解但不包括 "alpha" 注解。
• 枚举或常量值
• 组件配置结构

这些规则在正式发布之间执行，而不是在 master 或发布分支的任意提交之间执行。

规则 #1：API 元素只能通过递增 API 组的版本来移除。

一旦某个 API 元素以特定版本添加到 API 组，就不能从该版本中移除或对其行为进行显著更改，无论其处于哪个阶段。

规则 #2：API 对象必须能够在给定发布的不同 API 版本之间往返而不会丢失信息，除了某些版本中不存在的整个 REST 资源。

例如，一个对象可以作为 v1 写入，然后作为 v2 读回并转换为 v1，并且生成的 v1 资源将与原始资源相同。v2 中的表示可能与 v1 不同，但系统知道如何在两者之间双向转换。此外，v2 中添加的任何新字段都必须能够在 v1 和 v2 之间往返，这意味着 v1 可能需要添加一个等效字段或将其表示为注解。

规则 #3：给定轨道中的 API 版本不能被更不稳定的 API 版本弃用。

• GA API 版本可以替换 Beta 和 Alpha API 版本。
• Beta API 版本可以替换早期的 Beta 和 Alpha API 版本，但 **不能** 替换 GA API 版本。
• Alpha API 版本可以替换早期的 Alpha API 版本，但 **不能** 替换 GA 或 Beta API 版本。

规则 #4a：API 生命周期由 API 稳定性级别决定

• GA API 版本可能被标记为已弃用，但在 Kubernetes 的主版本中不得移除
• Beta API 版本在引入后不超过 9 个月或 3 个次要版本（以较长者为准）后弃用，并在弃用后不超过 9 个月或 3 个次要版本（以较长者为准）后停止服务
• Alpha API 版本可在任何版本中移除，无需事先弃用通知

这确保了 Beta API 支持涵盖最大支持版本偏差为 2 个发布版本，并且 API 不会停滞在不稳定的 Beta 版本上，从而累积生产使用量，当 Beta API 支持结束时，这将导致中断。

规则 #4b：给定组的“首选”API 版本和“存储版本”不得提前，直到发布了一个同时支持新版本和旧版本的版本。

用户必须能够升级到 Kubernetes 的新版本，然后回滚到旧版本，而无需将任何内容转换为新的 API 版本或遭受破坏（除非他们明确使用了仅在新版本中可用的功能）。这在对象的存储表示中尤为明显。

所有这些最好通过示例来说明。想象一个 Kubernetes 发布版本 X，它引入了一个新的 API 组。Kubernetes 大约每 4 个月发布一个新版本（每年 3 个）。下表描述了在后续一系列发布中支持的 API 版本。

REST 资源（又称 API 对象）

考虑一个名为 Widget 的假设 REST 资源，它出现在上述时间线的 API v1 中，并且需要被弃用。我们与发布版本 X+1 同步地记录并宣布弃用。Widget 资源仍然存在于 API 版本 v1（已弃用）中，但不存在于 v2alpha1 中。Widget 资源在包括 X+8 在内的发布版本中继续存在并运行。直到发布版本 X+9，当 API v1 过期时，Widget 资源才停止存在，并且行为被移除。

从 Kubernetes v1.19 开始，向已弃用的 REST API 端点发出 API 请求

1. 在 API 响应中返回一个 `Warning` 头（如 RFC7234，第 5.5 节中所定义）。

2. 为请求记录的审计事件添加一个`"k8s.io/deprecated":"true"`注解。

3. 在 `kube-apiserver` 进程中，将 `apiserver_requested_deprecated_apis` 仪表指标设置为 `1`。该指标具有 `group`、`version`、`resource`、`subresource` 标签，这些标签可以与 `apiserver_request_total` 指标连接，还有一个 `removed_release` 标签，表示 API 将在哪个 Kubernetes 版本中停止服务。以下 Prometheus 查询返回有关对将在 v1.22 中移除的已弃用 API 发出的请求的信息

   apiserver_requested_deprecated_apis{removed_release="1.22"} * on(group,version,resource,subresource) group_right() apiserver_request_total
   

REST 资源的字段

与整个 REST 资源一样，API v1 中存在的单个字段必须存在并正常运行，直到 API v1 被移除。与整个资源不同，v2 API 可以为该字段选择不同的表示方式，只要它能够进行往返转换即可。例如，一个名为“magnitude”的 v1 字段被弃用后，在 API v2 中可能被称为“deprecatedMagnitude”。当 v1 最终被移除时，该弃用字段可以从 v2 中移除。

枚举或常量值

与整个 REST 资源及其字段一样，API v1 中支持的常量值必须存在并正常运行，直到 API v1 被移除。

组件配置结构

组件配置版本化和管理方式与 REST 资源类似。

未来工作

随着时间的推移，Kubernetes 将引入更细粒度的 API 版本，届时这些规则将根据需要进行调整。

弃用标志或 CLI

Kubernetes 系统由几个相互协作的不同程序组成。有时，Kubernetes 发布版本可能会在这些程序中移除标志或 CLI 命令（统称为“CLI 元素”）。各个程序自然分为两个主要组——面向用户的程序和面向管理员的程序，它们的弃用策略略有不同。除非一个标志明确地带有“alpha”或“beta”前缀或文档说明，否则它被视为 GA。

CLI 元素实际上是系统 API 的一部分，但由于它们不像 REST API 那样进行版本控制，因此弃用规则如下：

规则 #5a：面向用户组件（例如 kubectl）的 CLI 元素在其宣布弃用后，必须至少运行

• GA：12 个月或 2 个发布版本（以较长者为准）
• Beta：3 个月或 1 个发布版本（以较长者为准）
• Alpha：0 个发布版本

规则 #5b：面向管理员的组件（例如 kubelet）的 CLI 元素在其宣布弃用后，必须至少运行

• GA：6 个月或 1 个发布版本（以较长者为准）
• Beta：3 个月或 1 个发布版本（以较长者为准）
• Alpha：0 个发布版本

规则 #5c：命令行界面 (CLI) 元素不能被弃用以支持稳定性更低的 CLI 元素

与 API 的规则 #3 类似，如果命令行界面的某个元素被替代实现替换，例如通过重命名现有元素，或者通过切换使用来自文件而非命令行参数的配置，则推荐的替代方案必须具有相同或更高的稳定性级别。

规则 #6：已弃用的 CLI 元素在使用时必须发出警告（可选禁用）。

弃用功能或行为

有时 Kubernetes 发布版本需要弃用系统中不受 API 或 CLI 控制的某些功能或行为。在这种情况下，弃用规则如下：

规则 #7：已弃用的行为在其宣布弃用后必须至少运行 1 年。

如果正在用需要工作才能适应更改的替代实现来替换功能或行为，则应尽可能简化过渡。如果替代实现受 Kubernetes 组织控制，则适用以下规则：

规则 #8：功能或行为不得因更不稳定的替代实现而被弃用

例如，一个普遍可用的功能不能被弃用，转而支持 Beta 版替代品。然而，Kubernetes 项目鼓励用户即使在替代实现达到相同成熟度之前也采用并过渡到它们。这对于探索功能的新用例或尽早获得替代品的反馈尤为重要。

替代实现有时可能是外部工具或产品，例如，某个功能可能从 kubelet 移到不受 Kubernetes 项目控制的容器运行时。在这种情况下，此规则无法适用，但必须努力确保存在不会损害组件成熟度级别的过渡路径。在容器运行时的示例中，这项工作可能涉及尝试确保流行的容器运行时具有在实现该替代行为时提供相同稳定性级别的版本。

功能和行为的弃用规则并不意味着系统的所有更改都受此策略的约束。这些规则仅适用于影响 Kubernetes 上运行应用程序的正确性或影响 Kubernetes 集群管理的重大、用户可见的行为，并且这些行为将被完全移除。

上述规则的一个例外是**特性门控**。特性门控是键值对，允许用户启用/禁用实验性功能。

特性门控旨在涵盖功能的开发生命周期——它们不打算成为长期 API。因此，预计它们将在功能达到 GA 或被删除后弃用和移除。

随着功能在各个阶段的演进，关联的特性门控也随之演变。功能生命周期与其对应的特性门控匹配如下：

• Alpha：特性门控默认禁用，用户可以启用。
• Beta：特性门控默认启用，用户可以禁用。
• GA：特性门控被弃用（参见“弃用”）并变得无法操作。
• GA，弃用期完成：特性门控被移除，不再接受对其的调用。

弃用

功能可以在 GA 之前的生命周期任何时候被移除。当功能在 GA 之前被移除时，其关联的特性门控也会被弃用。

当调用尝试禁用无法操作的特性门控时，调用失败，以避免可能悄无声息地运行的不受支持的场景。

在某些情况下，移除预 GA 功能需要相当长的时间。特性门控可以保持运行，直到其关联功能完全移除，届时特性门控本身可以被弃用。

当移除 GA 功能的特性门控也需要相当长的时间时，如果特性门控对功能没有影响，并且特性门控不会引起任何错误，则对特性门控的调用可以保持运行。

旨在由用户禁用的功能应包含在相关特性门控中禁用该功能的机制。

特性门控的版本控制与前面讨论的组件不同，因此弃用规则如下：

规则 #9：特性门控必须在其所控制的相应功能按以下方式转换生命周期阶段时被弃用。特性门控必须至少运行

• Beta 功能到 GA：6 个月或 2 个发布版本（以较长者为准）
• Beta 功能到 EOL：3 个月或 1 个发布版本（以较长者为准）
• Alpha 功能到 EOL：0 个发布版本

规则 #10：已弃用的特性门控在使用时必须发出警告。当特性门控被弃用时，它必须在发布说明和相应的 CLI 帮助中进行文档说明。警告和文档都必须指明特性门控是否处于非操作状态。

弃用指标

Kubernetes 控制平面的每个组件都会暴露指标（通常是 `/metrics` 端点），这些指标通常由集群管理员摄取。并非所有指标都相同：一些指标通常用作 SLI 或用于确定 SLO，这些指标往往更重要。其他指标在本质上更具实验性，或者主要用于 Kubernetes 开发过程。

因此，指标分为三个稳定性类别（`ALPHA`、`BETA`、`STABLE`）；这会影响 Kubernetes 发布期间指标的移除。这些类别由指标的感知重要性决定。弃用和移除指标的规则如下：

规则 #11a：指标，对于相应的稳定性类别，必须至少运行

• 稳定版 (STABLE)：4 个发布周期或 12 个月（以较长者为准）
• 测试版 (BETA)：2 个发布周期或 8 个月（以较长者为准）
• Alpha：0 个发布版本

规则 #11b：指标在其**宣布弃用**后，必须至少运行

• 稳定版 (STABLE)：3 个发布周期或 9 个月（以较长者为准）
• 测试版 (BETA)：1 个发布周期或 4 个月（以较长者为准）
• Alpha：0 个发布版本

已弃用指标的描述文本将以弃用通知字符串“（从 x.y 弃用）”为前缀，并在指标注册期间发出警告日志。与稳定的未弃用指标一样，已弃用指标将自动注册到指标端点，因此可见。

在随后的发布中（当指标的 `deprecatedVersion` 等于 `current_kubernetes_version - 3` 时），已弃用指标将成为**隐藏**指标。**与**已弃用指标**不同**，隐藏指标将**不再**自动注册到指标端点（因此是隐藏的）。但是，它们可以通过二进制文件上的命令行标志（`--show-hidden-metrics-for-version=`）显式启用。这为集群管理员提供了一个退出通道，如果他们未能对较早的弃用警告做出反应，则可以适当地从已弃用指标迁移。隐藏指标应在一个发布版本后删除。

例外

没有任何策略能涵盖所有可能的情况。本策略是一份动态文档，并将随着时间的推移而演变。在实践中，会存在不完全符合本策略的情况，或者本策略会成为严重障碍的情况。对于这些特定情况，应与 SIG 和项目负责人讨论，以找到最佳解决方案，始终牢记 Kubernetes 致力于成为一个稳定的系统，尽可能不破坏用户。例外情况将始终在所有相关发布说明中公布。