Kubernetes 弃用策略

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

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

弃用 API 的部分内容

由于 Kubernetes 是一个 API 驱动的系统，因此 API 随着时间的推移而发展，以反映对问题空间不断发展的理解。Kubernetes API 实际上是一组 API，称为“API 组”，每个 API 组都进行独立版本控制。API 版本分为 3 个主要轨道，每个轨道都有不同的弃用策略

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

以下规则 governing 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 支持结束后将 bị gián đoạn.

规则 #4b：给定组的“首选”API 版本和“存储版本”不得在发布支持新版本和先前版本的版本之后推进

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

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

REST 资源（又称 API 对象）

考虑一个名为 Widget 的假设 REST 资源，它存在于上述时间轴的 API v1 中，并且需要弃用。我们记录并宣布与版本 X+1 同步弃用。Widget 资源仍然存在于 API 版本 v1（已弃用）中，但不存在于 v2alpha1 中。Widget 资源在版本 X+8 之前（包括 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。该指标具有可连接到 apiserver_request_total 指标的 group、version、resource、subresource 标签，以及一个指示 API 将不再提供服务的 Kubernetes 版本的 removed_release 标签。以下 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 集群管理的重大、用户可见的行为，并且这些行为将被完全移除。

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

功能门控旨在涵盖功能的开发生命周期——它们不打算用作长期 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` 等于*当前 kubernetes 版本 - 3* 时），已弃用的指标将变为*隐藏*指标。**与**其已弃用的指标**不同**，隐藏指标将**不再**自动注册到指标端点（因此隐藏）。但是，可以通过二进制文件上的命令行标志（`--show-hidden-metrics-for-version=`）显式启用它们。如果集群管理员无法对较早的弃用警告做出反应，这将为他们提供一个适当迁移已弃用指标的紧急出口。隐藏指标应在一个版本后删除。

例外

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