弃用 API 迁移指南

随着 Kubernetes API 的演进，API 会定期进行重组或升级。当 API 演进时，旧的 API 会被弃用并最终移除。本页面包含从弃用的 API 版本迁移到更新、更稳定 API 版本时所需的信息。

按版本划分的已移除 API

v1.32

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

流控制资源

从 v1.32 开始，FlowSchema 和 PriorityLevelConfiguration 的 flowcontrol.apiserver.k8s.io/v1beta3 API 版本不再提供服务。

  • 请将清单和 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 开始，FlowSchema 和 PriorityLevelConfiguration 的 flowcontrol.apiserver.k8s.io/v1beta2 API 版本不再提供服务。

  • 请将清单和 API 客户端迁移至自 v1.29 起可用的 flowcontrol.apiserver.k8s.io/v1 API 版本，或者自 v1.26 起可用的 flowcontrol.apiserver.k8s.io/v1beta3 API 版本。
  • 所有现有的持久化对象均可通过新 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 开始，CSIStorageCapacity 的 storage.k8s.io/v1beta1 API 版本不再提供服务。

  • 请将清单和 API 客户端迁移至 storage.k8s.io/v1 API 版本，该版本自 v1.24 起可用。
  • 所有现有的持久化对象均可通过新 API 访问
  • 无显著变化

v1.26

v1.26 版本停止提供以下已弃用的 API 版本

流控制资源

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

  • 请将清单和 API 客户端迁移至 flowcontrol.apiserver.k8s.io/v1beta2 API 版本。
  • 所有现有的持久化对象均可通过新 API 访问
  • 无显著变化

HorizontalPodAutoscaler

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

  • 请将清单和 API 客户端迁移至 autoscaling/v2 API 版本，该版本自 v1.23 起可用。
  • 所有现有的持久化对象均可通过新 API 访问
  • 显著变化

v1.25

v1.25 版本停止提供以下已弃用的 API 版本

CronJob

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

  • 请将清单和 API 客户端迁移至 batch/v1 API 版本，该版本自 v1.21 起可用。
  • 所有现有的持久化对象均可通过新 API 访问
  • 无显著变化

EndpointSlice

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

  • 请将清单和 API 客户端迁移至 discovery.k8s.io/v1 API 版本，该版本自 v1.21 起可用。
  • 所有现有的持久化对象均可通过新 API 访问
  • discovery.k8s.io/v1 中的显著变化
    • 使用每个端点 (Endpoint) 的 nodeName 字段，而不是已弃用的 topology["kubernetes.io/hostname"] 字段
    • 使用每个端点 (Endpoint) 的 zone 字段，而不是已弃用的 topology["topology.kubernetes.io/zone"] 字段
    • topology 已被 deprecatedTopology 字段取代，该字段在 v1 中不可写

Event

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

  • 请将清单和 API 客户端迁移至 events.k8s.io/v1 API 版本，该版本自 v1.19 起可用。
  • 所有现有的持久化对象均可通过新 API 访问
  • events.k8s.io/v1 中的显著变化
    • type 仅限于 Normal 和 Warning
    • involvedObject 重命名为 regarding
    • 创建新的 events.k8s.io/v1 事件时，action、reason、reportingController 和 reportingInstance 为必填项
    • 使用 eventTime 代替已弃用的 firstTimestamp 字段（该字段已重命名为 deprecatedFirstTimestamp，在新的 events.k8s.io/v1 事件中不允许使用）
    • 使用 series.lastObservedTime 代替已弃用的 lastTimestamp 字段（该字段已重命名为 deprecatedLastTimestamp，在新的 events.k8s.io/v1 事件中不允许使用）
    • 使用 series.count 代替已弃用的 count 字段（该字段已重命名为 deprecatedCount，在新的 events.k8s.io/v1 事件中不允许使用）
    • 使用 reportingController 代替已弃用的 source.component 字段（该字段已重命名为 deprecatedSource.component，在新的 events.k8s.io/v1 事件中不允许使用）
    • 使用 reportingInstance 代替已弃用的 source.host 字段（该字段已重命名为 deprecatedSource.host，在新的 events.k8s.io/v1 事件中不允许使用）

HorizontalPodAutoscaler

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

  • 请将清单和 API 客户端迁移至 autoscaling/v2 API 版本，该版本自 v1.23 起可用。
  • 所有现有的持久化对象均可通过新 API 访问
  • 显著变化

PodDisruptionBudget

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

  • 请将清单和 API 客户端迁移至 policy/v1 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 安全性准入 (Pod Security Admission) 或 第三方准入 Webhook。有关迁移指南，请参阅从 PodSecurityPolicy 迁移到内置 Pod 安全性准入控制器。有关弃用的更多信息，请参阅PodSecurityPolicy 的弃用：过去、现在和未来。

RuntimeClass

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

  • 请将清单和 API 客户端迁移至 node.k8s.io/v1 API 版本，该版本自 v1.20 起可用。
  • 所有现有的持久化对象均可通过新 API 访问
  • 无显著变化

v1.22

v1.22 版本停止提供以下已弃用的 API 版本

Webhook 资源

从 v1.22 开始，MutatingWebhookConfiguration 和 ValidatingWebhookConfiguration 的 admissionregistration.k8s.io/v1beta1 API 版本不再提供服务。

  • 请将清单和 API 客户端迁移至 admissionregistration.k8s.io/v1 API 版本，该版本自 v1.16 起可用。
  • 所有现有的持久化对象均可通过新 API 访问
  • 显著变化
    • v1 版本中 webhooks[*].failurePolicy 的默认值从 Ignore 更改为 Fail
    • v1 版本中 webhooks[*].matchPolicy 的默认值从 Exact 更改为 Equivalent
    • v1 版本中 webhooks[*].timeoutSeconds 的默认值从 30s 更改为 10s
    • v1 版本中 webhooks[*].sideEffects 的默认值被移除，该字段变为必填项，且仅允许 None 和 NoneOnDryRun
    • v1 版本中 webhooks[*].admissionReviewVersions 的默认值被移除，该字段变为必填项（AdmissionReview 支持的版本为 v1 和 v1beta1）
    • 通过 admissionregistration.k8s.io/v1 创建的对象中，webhooks[*].name 在列表中必须是唯一的

CustomResourceDefinition

从 v1.22 开始，CustomResourceDefinition 的 apiextensions.k8s.io/v1beta1 API 版本不再提供服务。

  • 请将清单和 API 客户端迁移至 apiextensions.k8s.io/v1 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
    • 创建 v1 CustomResourceDefinition 对象时，现在必须包含 spec.versions[*].schema.openAPIV3Schema，且必须是一个结构化模式 (structural schema)
    • 创建 v1 CustomResourceDefinition 对象时不允许使用 spec.preserveUnknownFields: true；必须在模式定义中将其指定为 x-kubernetes-preserve-unknown-fields: true
    • 在 additionalPrinterColumns 项目中，JSONPath 字段在 v1 中重命名为 jsonPath（修复了 #66531）

APIService

从 v1.22 开始，APIService 的 apiregistration.k8s.io/v1beta1 API 版本不再提供服务。

  • 请将清单和 API 客户端迁移至 apiregistration.k8s.io/v1 API 版本，该版本自 v1.10 起可用。
  • 所有现有的持久化对象均可通过新 API 访问
  • 无显著变化

TokenReview

从 v1.22 开始，TokenReview 的 authentication.k8s.io/v1beta1 API 版本不再提供服务。

  • 请将清单和 API 客户端迁移至 authentication.k8s.io/v1 API 版本，该版本自 v1.6 起可用。
  • 无显著变化

SubjectAccessReview 资源

从 v1.22 开始，LocalSubjectAccessReview、SelfSubjectAccessReview、SubjectAccessReview 和 SelfSubjectRulesReview 的 authorization.k8s.io/v1beta1 API 版本不再提供服务。

  • 请将清单和 API 客户端迁移至 authorization.k8s.io/v1 API 版本，该版本自 v1.6 起可用。
  • 显著变化
    • spec.group 在 v1 中重命名为 spec.groups（修复了 #32709）

CertificateSigningRequest

从 v1.22 开始，CertificateSigningRequest 的 certificates.k8s.io/v1beta1 API 版本不再提供服务。

  • 请将清单和 API 客户端迁移至 certificates.k8s.io/v1 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

从 v1.22 开始，Lease 的 coordination.k8s.io/v1beta1 API 版本不再提供服务。

  • 请将清单和 API 客户端迁移至 coordination.k8s.io/v1 API 版本，该版本自 v1.14 起可用。
  • 所有现有的持久化对象均可通过新 API 访问
  • 无显著变化

Ingress

从 v1.22 开始，Ingress 的 extensions/v1beta1 和 networking.k8s.io/v1beta1 API 版本不再提供服务。

  • 请将清单和 API 客户端迁移至 networking.k8s.io/v1 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

从 v1.22 开始，IngressClass 的 networking.k8s.io/v1beta1 API 版本不再提供服务。

  • 请将清单和 API 客户端迁移至 networking.k8s.io/v1 API 版本，该版本自 v1.19 起可用。
  • 所有现有的持久化对象均可通过新 API 访问
  • 无显著变化

RBAC 资源

从 v1.22 开始，ClusterRole、ClusterRoleBinding、Role 和 RoleBinding 的 rbac.authorization.k8s.io/v1beta1 API 版本不再提供服务。

  • 请将清单和 API 客户端迁移至 rbac.authorization.k8s.io/v1 API 版本，该版本自 v1.8 起可用。
  • 所有现有的持久化对象均可通过新 API 访问
  • 无显著变化

PriorityClass

从 v1.22 开始，PriorityClass 的 scheduling.k8s.io/v1beta1 API 版本不再提供服务。

  • 请将清单和 API 客户端迁移至 scheduling.k8s.io/v1 API 版本，该版本自 v1.14 起可用。
  • 所有现有的持久化对象均可通过新 API 访问
  • 无显著变化

存储资源

从 v1.22 开始，CSIDriver、CSINode、StorageClass 和 VolumeAttachment 的 storage.k8s.io/v1beta1 API 版本不再提供服务。

  • 请将清单和 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

从 v1.16 开始，NetworkPolicy 的 extensions/v1beta1 API 版本不再提供服务。

  • 请将清单和 API 客户端迁移至 networking.k8s.io/v1 API 版本，该版本自 v1.8 起可用。
  • 所有现有的持久化对象均可通过新 API 访问

DaemonSet

从 v1.16 开始，DaemonSet 的 extensions/v1beta1 和 apps/v1beta2 API 版本不再提供服务。

  • 请将清单和 API 客户端迁移至 apps/v1 API 版本，该版本自 v1.9 起可用。
  • 所有现有的持久化对象均可通过新 API 访问
  • 显著变化
    • spec.templateGeneration 已被移除
    • spec.selector 现在为必填项，且创建后不可变；使用现有的模板标签作为选择器以实现无缝升级
    • spec.updateStrategy.type 现在默认为 RollingUpdate（extensions/v1beta1 中的默认值为 OnDelete）

Deployment

从 v1.16 开始，Deployment 的 extensions/v1beta1、apps/v1beta1 和 apps/v1beta2 API 版本不再提供服务。

  • 请将清单和 API 客户端迁移至 apps/v1 API 版本，该版本自 v1.9 起可用。
  • 所有现有的持久化对象均可通过新 API 访问
  • 显著变化
    • spec.rollbackTo 已被移除
    • spec.selector 现在为必填项，且创建后不可变；使用现有的模板标签作为选择器以实现无缝升级
    • spec.progressDeadlineSeconds 现在默认为 600 秒（extensions/v1beta1 中的默认值为无截止时间）
    • spec.revisionHistoryLimit 现在默认为 10（apps/v1beta1 中的默认值为 2，extensions/v1beta1 中的默认值为保留所有）
    • maxSurge 和 maxUnavailable 现在默认为 25%（extensions/v1beta1 中的默认值为 1）

StatefulSet

从 v1.16 开始，StatefulSet 的 apps/v1beta1 和 apps/v1beta2 API 版本不再提供服务。

  • 请将清单和 API 客户端迁移至 apps/v1 API 版本，该版本自 v1.9 起可用。
  • 所有现有的持久化对象均可通过新 API 访问
  • 显著变化
    • spec.selector 现在为必填项，且创建后不可变；使用现有的模板标签作为选择器以实现无缝升级
    • spec.updateStrategy.type 现在默认为 RollingUpdate（apps/v1beta1 中的默认值为 OnDelete）

ReplicaSet

从 v1.16 开始，ReplicaSet 的 extensions/v1beta1、apps/v1beta1 和 apps/v1beta2 API 版本不再提供服务。

  • 请将清单和 API 客户端迁移至 apps/v1 API 版本，该版本自 v1.9 起可用。
  • 所有现有的持久化对象均可通过新 API 访问
  • 显著变化
    • spec.selector 现在为必填项，且创建后不可变；使用现有的模板标签作为选择器以实现无缝升级

PodSecurityPolicy

从 v1.16 开始，PodSecurityPolicy 的 extensions/v1beta1 API 版本不再提供服务。

  • 请将清单和 API 客户端迁移至 policy/v1beta1 API 版本，该版本自 v1.10 起可用。
  • 请注意，PodSecurityPolicy 的 policy/v1beta1 API 版本将在 v1.25 中移除。

如何应对

测试已弃用 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。


最后修改时间：2025年5月16日 下午 2:49 (PST)：更新 v1.32 的弃用指南 (9f1af2971c)