弃用 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 版本

流控制资源

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

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

CSIStorageCapacity 的 storage.k8s.io/v1beta1 API 版本自 v1.27 起不再提供。

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

v1.26

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

流控制资源

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

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

HorizontalPodAutoscaler

HorizontalPodAutoscaler 的 autoscaling/v2beta2 API 版本自 v1.26 起不再提供。

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

v1.25

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

定时作业

CronJob 的 batch/v1beta1 API 版本自 v1.25 起不再提供。

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

EndpointSlice

EndpointSlice 的 discovery.k8s.io/v1beta1 API 版本自 v1.25 起不再提供。

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

Event 的 events.k8s.io/v1beta1 API 版本自 v1.25 起不再提供。

  • 将清单和 API 客户端迁移到使用 events.k8s.io/v1 API 版本,该版本自 v1.19 起可用。
  • 所有现有持久化对象都可以通过新的 API 访问
  • events.k8s.io/v1 中的显著变化
    • type 仅限于 NormalWarning
    • involvedObject 重命名为 regarding
    • 创建新的 events.k8s.io/v1 Event 时,actionreasonreportingControllerreportingInstance 是必需的
    • 使用 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

HorizontalPodAutoscaler 的 autoscaling/v2beta1 API 版本自 v1.25 起不再提供。

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

PodDisruptionBudget

PodDisruptionBudget 的 policy/v1beta1 API 版本自 v1.25 起不再提供。

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

policy/v1beta1 API 版本的 PodSecurityPolicy 自 v1.25 起不再提供,并且 PodSecurityPolicy 准入控制器将被移除。

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

RuntimeClass

RuntimeClass 的 node.k8s.io/v1beta1 API 版本自 v1.25 起不再提供。

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

v1.22

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

Webhook 资源

MutatingWebhookConfiguration 和 ValidatingWebhookConfiguration 的 admissionregistration.k8s.io/v1beta1 API 版本自 v1.22 起不再提供。

  • 将清单和 API 客户端迁移到使用 admissionregistration.k8s.io/v1 API 版本,该版本自 v1.16 起可用。
  • 所有现有持久化对象都可以通过新的 API 访问
  • 显著变化
    • webhooks[*].failurePolicy 的默认值在 v1 中从 Ignore 更改为 Fail
    • webhooks[*].matchPolicy 的默认值在 v1 中从 Exact 更改为 Equivalent
    • webhooks[*].timeoutSeconds 的默认值在 v1 中从 30s 更改为 10s
    • webhooks[*].sideEffects 的默认值已移除,并且该字段在 v1 中变为必需,只允许 NoneNoneOnDryRun
    • webhooks[*].admissionReviewVersions 的默认值已移除,并且该字段在 v1 中变为必需(AdmissionReview 支持的版本为 v1v1beta1
    • 通过 admissionregistration.k8s.io/v1 创建的对象,webhooks[*].name 在列表中必须是唯一的

CustomResourceDefinition

CustomResourceDefinition 的 apiextensions.k8s.io/v1beta1 API 版本自 v1.22 起不再提供。

  • 将清单和 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 现在是必需的,并且必须是结构化模式
    • 创建 v1 CustomResourceDefinition 对象时,不允许使用 spec.preserveUnknownFields: true;必须在模式定义中将其指定为 x-kubernetes-preserve-unknown-fields: true
    • additionalPrinterColumns 项目中,JSONPath 字段在 v1 中已重命名为 jsonPath(修复了 #66531

APIService

APIService 的 apiregistration.k8s.io/v1beta1 API 版本自 v1.22 起不再提供。

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

TokenReview

TokenReview 的 authentication.k8s.io/v1beta1 API 版本自 v1.22 起不再提供。

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

SubjectAccessReview 资源

LocalSubjectAccessReview、SelfSubjectAccessReview、SubjectAccessReview 和 SelfSubjectRulesReview 的 authorization.k8s.io/v1beta1 API 版本自 v1.22 起不再提供。

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

CertificateSigningRequest

CertificateSigningRequest 的 certificates.k8s.io/v1beta1 API 版本自 v1.22 起不再提供。

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

Lease 的 coordination.k8s.io/v1beta1 API 版本自 v1.22 起不再提供。

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

Ingress

Ingress 的 extensions/v1beta1networking.k8s.io/v1beta1 API 版本自 v1.22 起不再提供。

  • 将清单和 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。选项有 PrefixExactImplementationSpecific。要匹配未定义的 v1beta1 行为,请使用 ImplementationSpecific

IngressClass

IngressClass 的 networking.k8s.io/v1beta1 API 版本自 v1.22 起不再提供。

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

RBAC 资源

ClusterRole、ClusterRoleBinding、Role 和 RoleBinding 的 rbac.authorization.k8s.io/v1beta1 API 版本自 v1.22 起不再提供。

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

PriorityClass

PriorityClass 的 scheduling.k8s.io/v1beta1 API 版本自 v1.22 起不再提供。

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

存储资源

CSIDriver、CSINode、StorageClass 和 VolumeAttachment 的 storage.k8s.io/v1beta1 API 版本自 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 在 storage.k8s.io/v1 v1.13 中可用
  • 所有现有持久化对象都可以通过新的 API 访问
  • 无显著变化

v1.16

v1.16 版本停止提供以下废弃的 API 版本

NetworkPolicy

NetworkPolicy 的 extensions/v1beta1 API 版本自 v1.16 起不再提供。

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

DaemonSet

DaemonSet 的 extensions/v1beta1apps/v1beta2 API 版本自 v1.16 起不再提供。

  • 将清单和 API 客户端迁移到使用 apps/v1 API 版本,该版本自 v1.9 起可用。
  • 所有现有持久化对象都可以通过新的 API 访问
  • 显著变化
    • spec.templateGeneration 已移除
    • spec.selector 现在是必需的,并且创建后不可变;使用现有模板标签作为选择器以实现无缝升级
    • spec.updateStrategy.type 现在默认为 RollingUpdateextensions/v1beta1 中的默认值为 OnDelete

部署

Deployment 的 extensions/v1beta1apps/v1beta1apps/v1beta2 API 版本自 v1.16 起不再提供。

  • 将清单和 API 客户端迁移到使用 apps/v1 API 版本,该版本自 v1.9 起可用。
  • 所有现有持久化对象都可以通过新的 API 访问
  • 显著变化
    • spec.rollbackTo 已移除
    • spec.selector 现在是必需的,并且创建后不可变;使用现有模板标签作为选择器以实现无缝升级
    • spec.progressDeadlineSeconds 现在默认为 600 秒(extensions/v1beta1 中的默认值为无期限)
    • spec.revisionHistoryLimit 现在默认为 10apps/v1beta1 中的默认值为 2extensions/v1beta1 中的默认值为保留所有)
    • maxSurgemaxUnavailable 现在默认为 25%extensions/v1beta1 中的默认值为 1

StatefulSet

StatefulSet 的 apps/v1beta1apps/v1beta2 API 版本自 v1.16 起不再提供。

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

副本集

ReplicaSet 的 extensions/v1beta1apps/v1beta1apps/v1beta2 API 版本自 v1.16 起不再提供。

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

PodSecurityPolicy

PodSecurityPolicy 的 extensions/v1beta1 API 版本自 v1.16 起不再提供。

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

上次修改时间为 2025 年 5 月 16 日太平洋夏令时下午 2:49:更新了 v1.32 的废弃指南 (9f1af2971c)