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 组。大约每 4 个月（每年 3 次）发布一个新的 Kubernetes 版本。下表描述了后续版本中支持哪些 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. 设置 apiserver_requested_deprecated_apis 指标量规，在 kube-apiserver 进程中设置为 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 可以为该字段选择不同的表示形式，只要可以往返传输即可。例如，在 API v2 中，一个名为“magnitude”的 v1 字段可能会被命名为“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（功能门控）。功能门控是键值对，允许用户启用/禁用实验性功能。

功能门控旨在涵盖功能的开发生命周期——它们不打算作为长期 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 个版本

已弃用的指标将在其描述文本前加上弃用通知字符串 '(Deprecated from x.y)'，并在指标注册期间发出警告日志。与稳定的未弃用指标一样，已弃用的指标将自动注册到指标端点，因此可见。

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

例外情况

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