Kubernetes 1.22 版本中的 API 和功能移除：你需要了解的要点

随着 Kubernetes API 的演进，API 会定期进行重组或升级。当 API 演进时，被替换的旧 API 会被弃用，并最终被移除。请参阅Kubernetes API 移除以了解更多关于 Kubernetes 移除 API 的策略。

我们想确保你注意到即将到来的一些移除。这些是你在当前支持的 Kubernetes 版本中可以使用、但已被弃用的 Beta API。移除所有这些 API 的原因是它们已被更新的稳定 (“GA”) API 所取代。

预计于 2021 年 8 月发布的 Kubernetes 1.22 将移除许多已弃用的 API。更新：Kubernetes 1.22: Reaching New Peaks 提供了 v1.22 版本的详细信息。

Kubernetes v1.22 的 API 移除

v1.22 版本将停止提供我们在下面列出的 API 版本。这些都是 Beta API，之前已弃用，推荐使用更新、更稳定的 API 版本。

• ValidatingWebhookConfiguration 和 MutatingWebhookConfiguration API 的 Beta 版本（即 admissionregistration.k8s.io/v1beta1 API 版本）
• Beta CustomResourceDefinition API (apiextensions.k8s.io/v1beta1)
• Beta APIService API (apiregistration.k8s.io/v1beta1)
• Beta TokenReview API (authentication.k8s.io/v1beta1)
• SubjectAccessReview、LocalSubjectAccessReview、SelfSubjectAccessReview 的 Beta API 版本（来自 authorization.k8s.io/v1beta1 的 API 版本）
• Beta CertificateSigningRequest API (certificates.k8s.io/v1beta1)
• Beta Lease API (coordination.k8s.io/v1beta1)
• 所有 Beta Ingress API（即 extensions/v1beta1 和 networking.k8s.io/v1beta1 API 版本）

Kubernetes 文档涵盖了 v1.22 的这些 API 移除，并解释了每个 API 在 Beta 和 Stable 版本之间的变化。

该怎么做

我们将逐一介绍受这些移除影响的每个资源，并解释你需要采取的步骤。

Ingress

迁移到使用自 v1.19 起可用的 networking.k8s.io/v1 Ingress API，参见Ingress 晋级为通用可用。
相关的 API IngressClass 旨在补充 Ingress 概念，允许你在一个集群内配置多种类型的 Ingress。如果你目前使用已弃用的 kubernetes.io/ingress.class annotation，请计划切换到使用 .spec.ingressClassName 字段。
在任何运行 Kubernetes v1.19 或更高版本的集群上，你都可以使用 v1 API 来检索或更新现有的 Ingress 对象，即使它们是使用旧的 API 版本创建的。

将 Ingress 转换为 v1 API 时，你应该检查该 Ingress 中的每条规则。较旧的 Ingress 使用遗留的 ImplementationSpecific 路径类型。请将路径匹配从 ImplementationSpecific 切换到 Prefix 或 Exact。迁移到这些替代路径类型的好处之一是，可以在不同的 Ingress Class 之间更容易地迁移。

ⓘ 除了升级你作为客户端对 Ingress API 的使用外，还要确保你使用的每个 ingress 控制器都与 v1 Ingress API 兼容。阅读 Ingress 先决条件以了解更多关于 Ingress 和 ingress 控制器的背景信息。

ValidatingWebhookConfiguration 和 MutatingWebhookConfiguration

迁移到使用自 v1.16 起可用的 ValidatingWebhookConfiguration 和 MutatingWebhookConfiguration 的 admissionregistration.k8s.io/v1 API 版本。
你可以使用 v1 API 来检索或更新现有对象，即使它们是使用旧的 API 版本创建的。

CustomResourceDefinition

迁移到使用自 v1.16 起可用的 CustomResourceDefinition apiextensions.k8s.io/v1 API。
你可以使用 v1 API 来检索或更新现有对象，即使它们是使用旧的 API 版本创建的。如果你在集群中定义了任何自定义资源，在你升级后，这些资源仍将继续提供服务。

如果你使用外部 CustomResourceDefinition，你可以使用 kubectl convert 将现有清单文件转换为使用更新的 API。由于 Beta 和 Stable CustomResourceDefinition 之间存在一些功能差异，建议你在升级后测试每个自定义资源定义，以确保它们按预期工作。

APIService

迁移到使用自 v1.10 起可用的 apiregistration.k8s.io/v1 APIService API。
你可以使用 v1 API 来检索或更新现有对象，即使它们是使用旧的 API 版本创建的。如果你已经使用 APIService 对象进行了 API 聚合，升级后这种聚合将继续工作。

TokenReview

迁移到使用自 v1.10 起可用的 authentication.k8s.io/v1 TokenReview API。

除了通过 HTTP 提供此 API 外，Kubernetes API 服务器还使用相同的格式向 webhooks 发送 TokenReview。v1.22 版本默认仍继续使用 v1beta1 API 发送给 webhooks 的 TokenReview。有关切换到 Stable API 的具体提示，请参阅展望未来。

SubjectAccessReview、SelfSubjectReview 和 LocalSubjectAccessReview

迁移到使用自 v1.6 起可用的这些授权 API 的 authorization.k8s.io/v1 版本。

CertificateSigningRequest

迁移到使用自 v1.19 起可用的 certificates.k8s.io/v1 CertificateSigningRequest API。
你可以使用 v1 API 来检索或更新现有对象，即使它们是使用旧的 API 版本创建的。现有已签发的证书在升级后仍然有效。

Lease

迁移到使用自 v1.14 起可用的 coordination.k8s.io/v1 Lease API。
你可以使用 v1 API 来检索或更新现有对象，即使它们是使用旧的 API 版本创建的。

kubectl convert

有一个 kubectl 插件提供了 kubectl convert 子命令。它是一个官方插件，你可以作为 Kubernetes 的一部分下载。有关更多详情，请参阅下载 Kubernetes。

你可以使用 kubectl convert 更新清单文件以使用不同的 API 版本。例如，如果你在源代码控制中有使用 Beta Ingress API 的清单，你可以检出该定义，并运行 kubectl convert -f <清单文件> --output-version <group>/<version>。你可以使用 kubectl convert 命令自动转换现有清单。

例如，要将旧的 Ingress 定义转换为 networking.k8s.io/v1，你可以运行

kubectl convert -f ./legacy-ingress.yaml --output-version networking.k8s.io/v1

自动转换使用与 Kubernetes 控制平面如何更新最初使用旧 API 版本创建的对象类似的技术。由于它是机械转换，你可能需要手动修改清单以调整默认值等。

排练升级过程

如果你管理集群的 API Server 组件，可以在升级到 Kubernetes v1.22 之前尝试移除这些 API。

为此，将以下内容添加到 kube-apiserver 命令行参数中

--runtime-config=admissionregistration.k8s.io/v1beta1=false,apiextensions.k8s.io/v1beta1=false,apiregistration.k8s.io/v1beta1=false,authentication.k8s.io/v1beta1=false,authorization.k8s.io/v1beta1=false,certificates.k8s.io/v1beta1=false,coordination.k8s.io/v1beta1=false,extensions/v1beta1/ingresses=false,networking.k8s.io/v1beta1=false

（作为一个副作用，这也将关闭 EndpointSlice 的 v1beta1 版本 - 在测试时请注意这一点）。

一旦你将集群中的所有 kube-apiserver 都切换到使用此设置，这些 Beta API 将被移除。你可以测试 API 客户端（kubectl、部署工具、自定义控制器等）是否仍然按预期工作，如果需要，你无需计划更具破坏性的降级即可恢复。

给软件作者的建议

也许你正在阅读本文，因为你是一个与 Kubernetes 集成的附加组件或其他组件的开发者？

如果你开发 ingress 控制器、webhook 认证器、API 聚合或任何依赖于这些已弃用 API 的其他工具，你应该已经开始切换你的软件。

你可以使用排练升级过程中的提示来运行你自己的仅使用新 API 的 Kubernetes 集群，并确保你的代码正常工作。对于你的文档，请确保读者了解他们应为 Kubernetes v1.22 升级采取的任何步骤。

在可能的情况下，帮助你的用户尽早（可能在测试环境中）采用新 API，以便他们可以向你提供有关任何问题的反馈。

Kubernetes v1.25 中还有一些更多的弃用，所以也请计划涵盖这些内容。

Kubernetes API 移除

这里提供一些关于为什么 Kubernetes 会移除某些 API 的背景信息，以及关于 Kubernetes 中稳定 API 的承诺。

Kubernetes 对其功能（包括 Kubernetes API）遵循明确定义的弃用策略。该策略允许替换 Kubernetes 中的稳定 (“GA”) API。重要的是，此策略意味着只有当该 API 的更新稳定版本可用时，稳定 API 才会被弃用。

这一稳定性保证很重要：如果你正在使用稳定的 Kubernetes API，将来发布的版本绝不会强迫你切换到 Alpha 或 Beta 功能。

早期阶段则不同。Alpha 功能正在测试中，可能不完整。几乎所有 Alpha 功能都默认禁用。Kubernetes 版本可以并且确实会移除未能成功实现的 Alpha 功能。

Alpha 阶段之后是 Beta 阶段。这些功能通常默认启用；如果测试顺利，该功能可以升级到稳定版。否则，可能需要重新设计。

去年，Kubernetes 正式采纳了一项针对已进入 Beta 阶段的 API 的策略

对于 Kubernetes REST API，当一个新功能的 API 进入 Beta 阶段时，就会开始倒计时。该 Beta 版 API 现在有三个发行版本的时间……要么

• 转为 GA 版并废弃 Beta 版，或者
• 拥有一个新的 Beta 版本（并废弃之前的 Beta 版）。

在那篇文章发表时，Kubernetes 的三个发行版本大约相当于九个日历月。就在那个月晚些时候，Kubernetes 采用了每年发布三个版本的新发布节奏，因此倒计时周期现在大约是十二个日历月。

无论 API 移除是因为 Beta 功能升级到稳定版，还是因为该 API 尚未证明成功，Kubernetes 都将继续遵循其废弃策略移除 API，并确保在文档中说明迁移选项。

展望未来

如果您使用 webhook 认证检查，这里有一个相关的设置项。未来某个 Kubernetes 版本将默认切换为使用 authentication.k8s.io/v1 API 向 webhooks 发送 TokenReview 对象。目前，默认设置是向 webhooks 发送 authentication.k8s.io/v1beta1 TokenReviews，这对于 Kubernetes v1.22 仍然是默认设置。但是，如果您愿意，现在就可以切换到稳定版 API：将 --authentication-token-webhook-version=v1 添加到 kube-apiserver 的命令行选项中，并检查用于认证的 webhooks 是否仍按您预期的方式工作。

确认工作正常后，您可以在整个控制平面中保持 --authentication-token-webhook-version=v1 选项的设置不变。

计划于明年发布的 v1.25 版本将停止提供当前已稳定并持续了一段时间的几个 Kubernetes API 的 Beta 版本。同一个 v1.25 版本将移除 PodSecurityPolicy，该 API 已被废弃，并且不会升级到稳定版。有关更多信息，请参阅PodSecurityPolicy 废弃：过去、现在和未来。

计划在 Kubernetes 1.25 中进行的官方API 移除列表如下：

• Beta 版 CronJob API (batch/v1beta1)
• Beta 版 EndpointSlice API (networking.k8s.io/v1beta1)
• Beta 版 PodDisruptionBudget API (policy/v1beta1)
• Beta 版 PodSecurityPolicy API (policy/v1beta1)

想了解更多？

废弃事项会在 Kubernetes 发行注记中公布。您可以在 1.19、1.20 和 1.21 的发行注记中查看待废弃事项的公告。

有关废弃和移除过程的信息，请查阅官方 Kubernetes 废弃策略文档。

• ←上一篇
• 下一篇→