棄用 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 僅限於 Normal 和 Warning
    • involvedObject 重新命名為 regarding
    • 建立新的 events.k8s.io/v1 Event 時，action、reason、reportingController 和 reportingInstance 是必需的
    • 使用 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 中變為必需，只允許 None 和 NoneOnDryRun
    • webhooks[*].admissionReviewVersions 的預設值已移除，並且該欄位在 v1 中變為必需（AdmissionReview 支援的版本為 v1 和 v1beta1）
    • 透過 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/v1beta1 和 networking.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。選項有 Prefix、Exact 和 ImplementationSpecific。要匹配未定義的 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/v1beta1 和 apps/v1beta2 API 版本自 v1.16 起不再提供。

  • 將清單和 API 客戶端遷移到使用 apps/v1 API 版本，該版本自 v1.9 起可用。
  • 所有現有持久化物件都可以透過新的 API 訪問
  • 顯著變化
    • spec.templateGeneration 已移除
    • spec.selector 現在是必需的，並且建立後不可變；使用現有模板標籤作為選擇器以實現無縫升級
    • spec.updateStrategy.type 現在預設為 RollingUpdate（extensions/v1beta1 中的預設值為 OnDelete）

部署

Deployment 的 extensions/v1beta1、apps/v1beta1 和 apps/v1beta2 API 版本自 v1.16 起不再提供。

  • 將清單和 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

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

  • 將清單和 API 客戶端遷移到使用 apps/v1 API 版本，該版本自 v1.9 起可用。
  • 所有現有持久化物件都可以透過新的 API 訪問
  • 顯著變化
    • spec.selector 現在是必需的，並且建立後不可變；使用現有模板標籤作為選擇器以實現無縫升級
    • spec.updateStrategy.type 現在預設為 RollingUpdate（apps/v1beta1 中的預設值為 OnDelete）

副本集

ReplicaSet 的 extensions/v1beta1、apps/v1beta1 和 apps/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)