已弃用 API 的迁移指南

随着 Kubernetes API 的演化，API 会周期性地被重组或升级。当 API 演化时，老的 API 会被弃用并被最终删除。本页面包含你在将已弃用 API 版本迁移到新的更稳定的 API 版本时需要了解的知识。

各发行版本中移除的 API

v1.32

v1.32 发行版本将停止提供以下已弃用的 API 版本：

流控制资源

FlowSchema 和 PriorityLevelConfiguration 的 flowcontrol.apiserver.k8s.io/v1beta3 API 版本将不再在 v1.32 中提供。

迁移清单和 API 客户端以使用 flowcontrol.apiserver.k8s.io/v1 API 版本（自 v1.29 起可用）。
所有现有的持久对象都可以通过新的 API 访问。
flowcontrol.apiserver.k8s.io/v1 中的显着变化：
- PriorityLevelConfiguration 的 spec.limited.nominalConcurrencyShares 字段仅在未指定时默认为 30，并且显式值 0 时不会更改为 30。

v1.29

v1.29 发行版本停止支持以下已弃用的 API 版本：

流控制资源

从 v1.29 版本开始不再提供 flowcontrol.apiserver.k8s.io/v1beta2 API 版本的 FlowSchema 和 PriorityLevelConfiguration。

迁移清单和 API 客户端使用 flowcontrol.apiserver.k8s.io/v1 API 版本（自 v1.29 版本开始可用），或 flowcontrol.apiserver.k8s.io/v1beta3 API 版本（自 v1.26 起可用）；
所有的已保存的对象都可以通过新的 API 来访问；
flowcontrol.apiserver.k8s.io/v1 中的显着变化：
- PriorityLevelConfiguration 的 spec.limited.assuredConcurrencyShares 字段已被重命名为 spec.limited.nominalConcurrencyShares，仅在未指定时默认为 30，并且显式值 0 不会更改为 30。
flowcontrol.apiserver.k8s.io/v1beta3 中需要额外注意的变更：
- PriorityLevelConfiguration 的 spec.limited.assuredConcurrencyShares 字段已被更名为 spec.limited.nominalConcurrencyShares。

v1.27

v1.27 发行版本停止支持以下已弃用的 API 版本：

CSIStorageCapacity

从 v1.27 版本开始不再提供 storage.k8s.io/v1beta1 API 版本的 CSIStorageCapacity。

自 v1.24 版本起，迁移清单和 API 客户端使用 storage.k8s.io/v1 API 版本
所有现有的持久化对象都可以通过新的 API 访问
没有需要额外注意的变更

v1.26

v1.26 发行版本中将去除以下已弃用的 API 版本：

流控制资源

从 v1.26 版本开始不再提供 flowcontrol.apiserver.k8s.io/v1beta1 API 版本的 FlowSchema 和 PriorityLevelConfiguration。

迁移清单和 API 客户端使用 flowcontrol.apiserver.k8s.io/v1beta2 API 版本；
所有的已保存的对象都可以通过新的 API 来访问；
没有需要额外注意的变更。

HorizontalPodAutoscaler

从 v1.26 版本开始不再提供 autoscaling/v2beta2 API 版本的 HorizontalPodAutoscaler。

迁移清单和 API 客户端使用 autoscaling/v2 API 版本，此 API 从 v1.23 版本开始可用；
所有的已保存的对象都可以通过新的 API 来访问。
值得注意的变更：
- targetAverageUtilization 被替换为 target.averageUtilization 和 target.type: Utilization。请参阅基于多项度量指标和自定义度量指标自动扩缩。

v1.25

v1.25 发行版本将停止提供以下已废弃 API 版本：

CronJob

从 v1.25 版本开始不再提供 batch/v1beta1 API 版本的 CronJob。

迁移清单和 API 客户端使用 batch/v1 API 版本，此 API 从 v1.21 版本开始可用；
所有的已保存的对象都可以通过新的 API 来访问；
没有需要额外注意的变更。

EndpointSlice

从 v1.25 版本开始不再提供 discovery.k8s.io/v1beta1 API 版本的 EndpointSlice。

迁移清单和 API 客户端使用 discovery.k8s.io/v1 API 版本，此 API 从 v1.21 版本开始可用；
所有的已保存的对象都可以通过新的 API 来访问；
discovery.k8s.io/v1 中值得注意的变更有：
- 使用每个 Endpoint 的 nodeName 字段而不是已被弃用的 topology["kubernetes.io/hostname"] 字段；
- 使用每个 Endpoint 的 zone 字段而不是已被弃用的 topology["kubernetes.io/zone"] 字段；
- topology 字段被替换为 deprecatedTopology，并且在 v1 版本中不可写入。

Event

从 v1.25 版本开始不再提供 events.k8s.io/v1beta1 API 版本的 Event。

迁移清单和 API 客户端使用 events.k8s.io/v1 API 版本，此 API 从 v1.19 版本开始可用；
所有的已保存的对象都可以通过新的 API 来访问；

events.k8s.io/v1 中值得注意的变更有：
- type 字段只能设置为 Normal 和 Warning 之一；
- involvedObject 字段被更名为 regarding；
- action、reason、reportingController 和 reportingInstance 字段在创建新的 events.k8s.io/v1 版本 Event 时都是必需的字段；
- 使用 eventTime 而不是已被弃用的 firstTimestamp 字段（该字段已被更名为 deprecatedFirstTimestamp，且不允许出现在新的 events.k8s.io/v1 Event 对象中）；
- 使用 series.lastObservedTime 而不是已被弃用的 lastTimestamp 字段（该字段已被更名为 deprecatedLastTimestamp，且不允许出现在新的 events.k8s.io/v1 Event 对象中）；
- 使用 series.count 而不是已被弃用的 count 字段（该字段已被更名为 deprecatedCount，且不允许出现在新的 events.k8s.io/v1 Event 对象中）；
- 使用 reportingController 而不是已被弃用的 source.component 字段（该字段已被更名为 deprecatedSource.component，且不允许出现在新的 events.k8s.io/v1 Event 对象中）；
- 使用 reportingInstance 而不是已被弃用的 source.host 字段（该字段已被更名为 deprecatedSource.host，且不允许出现在新的 events.k8s.io/v1 Event 对象中）。

HorizontalPodAutoscaler

从 v1.25 版本开始不再提供 autoscaling/v2beta1 API 版本的 HorizontalPodAutoscaler。

迁移清单和 API 客户端使用 autoscaling/v2 API 版本，此 API 从 v1.23 版本开始可用；
所有的已保存的对象都可以通过新的 API 来访问。
值得注意的变更：
- targetAverageUtilization 被替换为 target.averageUtilization 和 target.type: Utilization。请参阅基于多项度量指标和自定义度量指标自动扩缩。

PodDisruptionBudget

从 v1.25 版本开始不再提供 policy/v1beta1 API 版本的 PodDisruptionBudget。

迁移清单和 API 客户端使用 policy/v1 API 版本，此 API 从 v1.21 版本开始可用；
所有的已保存的对象都可以通过新的 API 来访问；
policy/v1 中需要额外注意的变更有：
- 在 policy/v1 版本的 PodDisruptionBudget 中将 spec.selector 设置为空（{}）时会选择名字空间中的所有 Pod（在 policy/v1beta1 版本中，空的 spec.selector 不会选择任何 Pod）。如果 spec.selector 未设置，则在两个 API 版本下都不会选择任何 Pod。

PodSecurityPolicy

从 v1.25 版本开始不再提供 policy/v1beta1 API 版本中的 PodSecurityPolicy，并且 PodSecurityPolicy 准入控制器也会被删除。

迁移到 Pod 安全准入或第三方准入 Webhook。有关迁移指南，请参阅从 PodSecurityPolicy 迁移到内置 PodSecurity 准入控制器。有关弃用的更多信息，请参阅 PodSecurityPolicy 弃用：过去、现在和未来。

RuntimeClass

从 v1.25 版本开始不再提供 node.k8s.io/v1beta1 API 版本中的 RuntimeClass。

迁移清单和 API 客户端使用 node.k8s.io/v1 API 版本，此 API 从 v1.20 版本开始可用；
所有的已保存的对象都可以通过新的 API 来访问；
没有需要额外注意的变更。

v1.22

v1.22 发行版本停止提供以下已废弃 API 版本：

Webhook 资源

admissionregistration.k8s.io/v1beta1 API 版本的 MutatingWebhookConfiguration 和 ValidatingWebhookConfiguration 不在 v1.22 版本中继续提供。

迁移清单和 API 客户端使用 admissionregistration.k8s.io/v1 API 版本，此 API 从 v1.16 版本开始可用；
所有的已保存的对象都可以通过新的 API 来访问；

值得注意的变更：
- webhooks[*].failurePolicy 在 v1 版本中默认值从 Ignore 改为 Fail
- webhooks[*].matchPolicy 在 v1 版本中默认值从 Exact 改为 Equivalent
- webhooks[*].timeoutSeconds 在 v1 版本中默认值从 30s 改为 10s
- webhooks[*].sideEffects 的默认值被删除，并且该字段变为必须指定；在 v1 版本中可选的值只能是 None 和 NoneOnDryRun 之一
- webhooks[*].admissionReviewVersions 的默认值被删除，在 v1 版本中此字段变为必须指定（AdmissionReview 的被支持版本包括 v1 和 v1beta1）
- webhooks[*].name 必须在通过 admissionregistration.k8s.io/v1 创建的对象列表中唯一

CustomResourceDefinition

apiextensions.k8s.io/v1beta1 API 版本的 CustomResourceDefinition 不在 v1.22 版本中继续提供。

迁移清单和 API 客户端使用 apiextensions.k8s.io/v1 API 版本，此 API 从 v1.16 版本开始可用；
所有的已保存的对象都可以通过新的 API 来访问；

值得注意的变更：
- spec.scope 的默认值不再是 Namespaced，该字段必须显式指定
- spec.version 在 v1 版本中被删除；应改用 spec.versions
- spec.validation 在 v1 版本中被删除；应改用 spec.versions[*].schema
- spec.subresources 在 v1 版本中被删除；应改用 spec.versions[*].subresources
- spec.additionalPrinterColumns 在 v1 版本中被删除；应改用 spec.versions[*].additionalPrinterColumns
- spec.conversion.webhookClientConfig 在 v1 版本中被移动到 spec.conversion.webhook.clientConfig 中
- spec.conversion.conversionReviewVersions 在 v1 版本中被移动到 spec.conversion.webhook.conversionReviewVersions
- spec.versions[*].schema.openAPIV3Schema 在创建 v1 版本的 CustomResourceDefinition 对象时变成必需字段，并且其取值必须是一个结构化的 Schema
- spec.preserveUnknownFields: true 在创建 v1 版本的 CustomResourceDefinition 对象时不允许指定；该配置必须在 Schema 定义中使用 x-kubernetes-preserve-unknown-fields: true 来设置
- 在 v1 版本中，additionalPrinterColumns 的条目中的 JSONPath 字段被更名为 jsonPath（补丁 #66531）

APIService

apiregistration/v1beta1 API 版本的 APIService 不在 v1.22 版本中继续提供。

迁移清单和 API 客户端使用 apiregistration.k8s.io/v1 API 版本，此 API 从 v1.10 版本开始可用；
所有的已保存的对象都可以通过新的 API 来访问；
没有需要额外注意的变更。

TokenReview

authentication.k8s.io/v1beta1 API 版本的 TokenReview 不在 v1.22 版本中继续提供。

迁移清单和 API 客户端使用 authentication.k8s.io/v1 API 版本，此 API 从 v1.6 版本开始可用；
所有的已保存的对象都可以通过新的 API 来访问；
没有需要额外注意的变更。

SubjectAccessReview resources

authorization.k8s.io/v1beta1 API 版本的 LocalSubjectAccessReview、 SelfSubjectAccessReview、SubjectAccessReview、SelfSubjectRulesReview 不在 v1.22 版本中继续提供。

迁移清单和 API 客户端使用 authorization.k8s.io/v1 API 版本，此 API 从 v1.6 版本开始可用；
所有的已保存的对象都可以通过新的 API 来访问；
需要额外注意的变更：
- spec.group 在 v1 版本中被更名为 spec.groups （补丁 #32709）

CertificateSigningRequest

certificates.k8s.io/v1beta1 API 版本的 CertificateSigningRequest 不在 v1.22 版本中继续提供。

迁移清单和 API 客户端使用 certificates.k8s.io/v1 API 版本，此 API 从 v1.19 版本开始可用；
所有的已保存的对象都可以通过新的 API 来访问；

certificates.k8s.io/v1 中需要额外注意的变更：
- 对于请求证书的 API 客户端而言：
  - spec.signerName 现在变成必需字段（参阅已知的 Kubernetes 签署者），并且通过 certificates.k8s.io/v1 API 不可以创建签署者为 kubernetes.io/legacy-unknown 的请求
  - spec.usages 现在变成必需字段，其中不可以包含重复的字符串值，并且只能包含已知的用法字符串
- 对于要批准或者签署证书的 API 客户端而言：
  - status.conditions 中不可以包含重复的类型
  - status.conditions[*].status 字段现在变为必需字段
  - status.certificate 必须是 PEM 编码的，而且其中只能包含 CERTIFICATE 数据块

Lease

coordination.k8s.io/v1beta1 API 版本的 Lease 不在 v1.22 版本中继续提供。

迁移清单和 API 客户端使用 coordination.k8s.io/v1 API 版本，此 API 从 v1.14 版本开始可用；
所有的已保存的对象都可以通过新的 API 来访问；
没有需要额外注意的变更。

Ingress

extensions/v1beta1 和 networking.k8s.io/v1beta1 API 版本的 Ingress 不在 v1.22 版本中继续提供。

迁移清单和 API 客户端使用 networking.k8s.io/v1 API 版本，此 API 从 v1.19 版本开始可用；
所有的已保存的对象都可以通过新的 API 来访问；

值得注意的变更：
- spec.backend 字段被更名为 spec.defaultBackend
- 后端的 serviceName 字段被更名为 service.name
- 数值表示的后端 servicePort 字段被更名为 service.port.number
- 字符串表示的后端 servicePort 字段被更名为 service.port.name
- 对所有要指定的路径，pathType 都成为必需字段。可选项为 Prefix、Exact 和 ImplementationSpecific。要匹配 v1beta1 版本中未定义路径类型时的行为，可使用 ImplementationSpecific

IngressClass

networking.k8s.io/v1beta1 API 版本的 IngressClass 不在 v1.22 版本中继续提供。

迁移清单和 API 客户端使用 networking.k8s.io/v1 API 版本，此 API 从 v1.19 版本开始可用；
所有的已保存的对象都可以通过新的 API 来访问；
没有需要额外注意的变更。

RBAC 资源

rbac.authorization.k8s.io/v1beta1 API 版本的 ClusterRole、ClusterRoleBinding、 Role 和 RoleBinding 不在 v1.22 版本中继续提供。

迁移清单和 API 客户端使用 rbac.authorization.k8s.io/v1 API 版本，此 API 从 v1.8 版本开始可用；
所有的已保存的对象都可以通过新的 API 来访问；
没有需要额外注意的变更。

PriorityClass

scheduling.k8s.io/v1beta1 API 版本的 PriorityClass 不在 v1.22 版本中继续提供。

迁移清单和 API 客户端使用 scheduling.k8s.io/v1 API 版本，此 API 从 v1.14 版本开始可用；
所有的已保存的对象都可以通过新的 API 来访问；
没有需要额外注意的变更。

存储资源

storage.k8s.io/v1beta1 API 版本的 CSIDriver、CSINode、StorageClass 和 VolumeAttachment 不在 v1.22 版本中继续提供。

迁移清单和 API 客户端使用 storage.k8s.io/v1 API 版本
- CSIDriver 从 v1.19 版本开始在 storage.k8s.io/v1 中提供；
- CSINode 从 v1.17 版本开始在 storage.k8s.io/v1 中提供；
- StorageClass 从 v1.6 版本开始在 storage.k8s.io/v1 中提供；
- VolumeAttachment 从 v1.13 版本开始在 storage.k8s.io/v1 中提供；
所有的已保存的对象都可以通过新的 API 来访问；
没有需要额外注意的变更。

v1.16

v1.16 发行版本停止提供以下已废弃 API 版本：

NetworkPolicy

extensions/v1beta1 API 版本的 NetworkPolicy 不在 v1.16 版本中继续提供。

迁移清单和 API 客户端使用 networking.k8s.io/v1 API 版本，此 API 从 v1.8 版本开始可用；
所有的已保存的对象都可以通过新的 API 来访问。

DaemonSet

extensions/v1beta1 和 apps/v1beta2 API 版本的 DaemonSet 在 v1.16 版本中不再继续提供。

迁移清单和 API 客户端使用 apps/v1 API 版本，此 API 从 v1.9 版本开始可用；
所有的已保存的对象都可以通过新的 API 来访问；

值得注意的变更：
- spec.templateGeneration 字段被删除
- spec.selector 现在变成必需字段，并且在对象创建之后不可变更；可以将现有模板的标签作为选择算符以实现无缝迁移。
- spec.updateStrategy.type 的默认值变为 RollingUpdate （extensions/v1beta1 API 版本中的默认值是 OnDelete）。

Deployment

extensions/v1beta1、apps/v1beta1 和 apps/v1beta2 API 版本的 Deployment 在 v1.16 版本中不再继续提供。

迁移清单和 API 客户端使用 apps/v1 API 版本，此 API 从 v1.9 版本开始可用；
所有的已保存的对象都可以通过新的 API 来访问；

值得注意的变更：
- spec.rollbackTo 字段被删除
- spec.selector 字段现在变为必需字段，并且在 Deployment 创建之后不可变更；可以使用现有的模板的标签作为选择算符以实现无缝迁移。
- spec.progressDeadlineSeconds 的默认值变为 600 秒（extensions/v1beta1 中的默认值是没有期限）
- spec.revisionHistoryLimit 的默认值变为 10 （apps/v1beta1 API 版本中此字段默认值为 2，在extensions/v1beta1 API 版本中的默认行为是保留所有历史记录）。
- maxSurge 和 maxUnavailable 的默认值变为 25% （在 extensions/v1beta1 API 版本中，这些字段的默认值是 1）。

StatefulSet

apps/v1beta1 和 apps/v1beta2 API 版本的 StatefulSet 在 v1.16 版本中不再继续提供。

迁移清单和 API 客户端使用 apps/v1 API 版本，此 API 从 v1.9 版本开始可用；
所有的已保存的对象都可以通过新的 API 来访问；

值得注意的变更：
- spec.selector 字段现在变为必需字段，并且在 StatefulSet 创建之后不可变更；可以使用现有的模板的标签作为选择算符以实现无缝迁移。
- spec.updateStrategy.type 的默认值变为 RollingUpdate （apps/v1beta1 API 版本中的默认值是 OnDelete）。

ReplicaSet

extensions/v1beta1、apps/v1beta1 和 apps/v1beta2 API 版本的 ReplicaSet 在 v1.16 版本中不再继续提供。

迁移清单和 API 客户端使用 apps/v1 API 版本，此 API 从 v1.9 版本开始可用；
所有的已保存的对象都可以通过新的 API 来访问；

值得注意的变更：
- spec.selector 现在变成必需字段，并且在对象创建之后不可变更；可以将现有模板的标签作为选择算符以实现无缝迁移。

PodSecurityPolicy

extensions/v1beta1 API 版本的 PodSecurityPolicy 在 v1.16 版本中不再继续提供。

迁移清单和 API 客户端使用 policy/v1beta1 API 版本，此 API 从 v1.10 版本开始可用；
注意 policy/v1beta1 API 版本的 PodSecurityPolicy 会在 v1.25 版本中移除。

需要做什么

在禁用已启用 API 的情况下执行测试

你可以通过在启动 API 服务器时禁用特定的 API 版本来模拟即将发生的 API 移除，从而完成测试。在 API 服务器启动参数中添加如下标志：

--runtime-config=<group>/<version>=false

例如：

--runtime-config=admissionregistration.k8s.io/v1beta1=false,apiextensions.k8s.io/v1beta1,...

定位何处使用了已弃用的 API

使用 1.19 及更高版本中可用的客户端警告、指标和审计信息来定位在何处使用了已弃用的 API。

迁移到未被弃用的 API

更新自定义的集成组件和控制器，调用未被弃用的 API
更改 YAML 文件引用未被弃用的 API
你可以用 kubectl-convert 命令自动转换现有对象：
```
kubectl convert -f <file> --output-version <group>/<version> 
```
例如，要将较老的 Deployment 版本转换为 apps/v1 版本，你可以运行：
```
kubectl convert -f ./my-deployment.yaml --output-version apps/v1 
```
这个转换可能使用了非理想的默认值。要了解更多关于特定资源的信息，请查阅 Kubernetes API 参考文档。
说明：
尽管实际上 kubectl convert 工具曾经是 kubectl 自身的一部分，但此工具不是默认安装的。如果想了解更多详情，可以阅读内置子命令的弃用和移除问题。
要了解如何在你的计算机上设置 kubectl convert，查阅适合你操作系统的页面： Linux、 macOS 或 Windows。

最后修改 April 30, 2024 at 12:30 AM PST: [zh-cn] Sync docs/reference/using-api (669794b911)

已弃用 API 的迁移指南

各发行版本中移除的 API

v1.32

流控制资源

v1.29

流控制资源

v1.27

CSIStorageCapacity

v1.26

流控制资源

HorizontalPodAutoscaler

v1.25

CronJob

EndpointSlice

Event

HorizontalPodAutoscaler

PodDisruptionBudget

PodSecurityPolicy

RuntimeClass

v1.22

Webhook 资源

CustomResourceDefinition

APIService

TokenReview

SubjectAccessReview resources

CertificateSigningRequest

Lease

Ingress

IngressClass

RBAC 资源

PriorityClass

存储资源

v1.16

NetworkPolicy

DaemonSet

Deployment

StatefulSet

ReplicaSet

PodSecurityPolicy

需要做什么

在禁用已启用 API 的情况下执行测试

定位何处使用了已弃用的 API

迁移到未被弃用的 API

说明：

反馈