Kubernetes 弃用策略

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

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

弃用 API 的部分

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

特定版本的 Kubernetes 可以支持任意数量的 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 并返回，这意味着 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 对象）

考虑一个假设的 REST 资源名为 Widget，它存在于上述时间线中的 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 gauge 度量设置为 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 可能选择对该字段采用不同的表示形式，只要它能够往返转换。例如，一个在 v1 中被弃用的名为 "magnitude" 的字段在 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 集群管理的重大、用户可见的行为，并且这些行为将被完全移除。

上述规则的一个例外是 feature gates（功能门）。Feature gates 是键值对，允许用户启用/禁用实验性功能。

Feature gates 旨在涵盖功能的开发生命周期——它们不是长期 API。因此，当一个功能达到 GA 或被取消时，它们预计会被弃用并移除。

随着功能经历各个阶段，关联的 feature gate 也会演变。功能生命周期与其相应的 feature gate 的匹配如下：

• Alpha：该 feature gate 默认禁用，用户可以启用。
• Beta：该 feature gate 默认启用，用户可以禁用。
• GA：该 feature gate 被弃用（参见“弃用”）并且变为非操作状态。
• GA，弃用窗口完成：该 feature gate 被移除，不再接受对其的调用。

弃用

功能可以在达到 GA 之前的任何生命周期阶段被移除。当功能在达到 GA 之前被移除时，其关联的 feature gates 也将被弃用。

当调用尝试禁用非操作状态的 feature gate 时，调用会失败，以避免可能在静默状态下运行的非受支持场景。

在某些情况下，移除 pre-GA 功能需要相当长的时间。Feature gates 可以保持操作状态，直到其关联的功能完全移除，届时 feature gate 本身可以被弃用。

当移除 GA 功能的 feature gate 也需要相当长的时间时，如果该 feature gate 对功能没有影响且不引起错误，则对 feature gates 的调用可能保持操作状态。

旨在由用户禁用的功能应在其关联的 feature gate 中包含禁用该功能的机制。

Feature gates 的版本控制与之前讨论的组件不同，因此弃用规则如下：

规则 #9：当其控制的相应功能按照如下方式转换生命周期阶段时，必须弃用 Feature gates。Feature gates 必须继续工作不少于：

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

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

弃用度量

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 个发布版本

已弃用度量的描述文本将前缀弃用通知字符串 '(Deprecated from x.y)'，并且在度量注册期间将发出警告日志。与它们稳定未弃用的对应度量一样，已弃用度量将自动注册到 metrics 端点并因此可见。

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

例外情况

任何策略都无法涵盖所有可能的情况。本策略是一份动态文档，将随着时间不断演进。实际上，有些情况无法完全适用本策略，或者本策略会成为严重的障碍。应与 SIG 和项目负责人讨论此类情况，以找到针对这些特定情况的最佳解决方案，始终牢记 Kubernetes 致力于成为一个稳定的系统，并尽可能地避免破坏用户的环境。例外情况将始终在所有相关的发布说明中宣布。