已棄用的 API 遷移指南

隨著 Kubernetes API 的演進，API 會定期重組或升級。當 API 演進時，舊的 API 會被棄用並最終移除。此頁面包含從已棄用的 API 版本遷移至更新、更穩定的 API 版本時您需要知道的資訊。

依發行版本移除的 API

v1.32

v1.32 發行版本將停止提供以下已棄用的 API 版本

流量控制資源

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

  • 遷移 manifest 和 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 起不再提供服務。

  • 遷移 manifest 和 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 開始，不再提供 CSIStorageCapacity 的 storage.k8s.io/v1beta1 API 版本。

  • 遷移 manifests 和 API client 以使用 storage.k8s.io/v1 API 版本，此版本自 v1.24 起可用。
  • 所有現有持久化物件都可以透過新的 API 存取
  • 無重大變更

v1.26

v1.26 版本停止提供下列已棄用的 API 版本

流量控制資源

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

  • 遷移 manifests 和 API client 以使用 flowcontrol.apiserver.k8s.io/v1beta2 API 版本。
  • 所有現有持久化物件都可以透過新的 API 存取
  • 無重大變更

HorizontalPodAutoscaler

從 v1.26 開始，不再提供 HorizontalPodAutoscaler 的 autoscaling/v2beta2 API 版本。

  • 遷移 manifests 和 API client 以使用 autoscaling/v2 API 版本，此版本自 v1.23 起可用。
  • 所有現有持久化物件都可以透過新的 API 存取
  • 重大變更

v1.25

v1.25 版本停止提供下列已棄用的 API 版本

CronJob

從 v1.25 開始，不再提供 CronJob 的 batch/v1beta1 API 版本。

  • 遷移 manifests 和 API client 以使用 batch/v1 API 版本，此版本自 v1.21 起可用。
  • 所有現有持久化物件都可以透過新的 API 存取
  • 無重大變更

EndpointSlice

從 v1.25 開始，不再提供 EndpointSlice 的 discovery.k8s.io/v1beta1 API 版本。

  • 遷移 manifests 和 API client 以使用 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 版本。

  • 遷移 manifests 和 API client 以使用 events.k8s.io/v1 API 版本，此版本自 v1.19 起可用。
  • 所有現有持久化物件都可以透過新的 API 存取
  • events.k8s.io/v1 中的重大變更
    • type 僅限於 Normal 和 Warning
    • involvedObject 已重新命名為 regarding
    • 建立新的 events.k8s.io/v1 Events 時，action、reason、reportingController 和 reportingInstance 為必填欄位
    • 使用 eventTime 而不是已棄用的 firstTimestamp 欄位 (該欄位已重新命名為 deprecatedFirstTimestamp，且不允許在新的 events.k8s.io/v1 Events 中使用)
    • 使用 series.lastObservedTime 而不是已棄用的 lastTimestamp 欄位 (該欄位已重新命名為 deprecatedLastTimestamp，且不允許在新的 events.k8s.io/v1 Events 中使用)
    • 使用 series.count 而不是已棄用的 count 欄位 (該欄位已重新命名為 deprecatedCount，且不允許在新的 events.k8s.io/v1 Events 中使用)
    • 使用 reportingController 而不是已棄用的 source.component 欄位 (該欄位已重新命名為 deprecatedSource.component，且不允許在新的 events.k8s.io/v1 Events 中使用)
    • 使用 reportingInstance 而不是已棄用的 source.host 欄位 (該欄位已重新命名為 deprecatedSource.host，且不允許在新的 events.k8s.io/v1 Events 中使用)

HorizontalPodAutoscaler

從 v1.25 開始，不再提供 HorizontalPodAutoscaler 的 autoscaling/v2beta1 API 版本。

  • 遷移 manifests 和 API client 以使用 autoscaling/v2 API 版本，此版本自 v1.23 起可用。
  • 所有現有持久化物件都可以透過新的 API 存取
  • 重大變更

PodDisruptionBudget

從 v1.25 開始，不再提供 PodDisruptionBudget 的 policy/v1beta1 API 版本。

  • 遷移 manifests 和 API client 以使用 policy/v1 API 版本，此版本自 v1.21 起可用。
  • 所有現有持久化物件都可以透過新的 API 存取
  • policy/v1 中的重大變更
    • 寫入 policy/v1 PodDisruptionBudget 的空 spec.selector ({}) 會選取命名空間中的所有 Pod (在 policy/v1beta1 中，空的 spec.selector 不會選取任何 Pod)。在任一 API 版本中，未設定的 spec.selector 都不會選取任何 Pod。

PodSecurityPolicy

從 v1.25 開始，不再提供 policy/v1beta1 API 版本中的 PodSecurityPolicy，並且將移除 PodSecurityPolicy 准入控制器。

遷移至 Pod Security Admission 或 第三方准入 webhook。如需遷移指南，請參閱從 PodSecurityPolicy 遷移至內建的 PodSecurity 准入控制器。如需關於棄用的更多資訊，請參閱PodSecurityPolicy 棄用：過去、現在與未來。

RuntimeClass

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

  • 遷移 manifests 和 API client 以使用 node.k8s.io/v1 API 版本，此版本自 v1.20 起可用。
  • 所有現有持久化物件都可以透過新的 API 存取
  • 無重大變更

v1.22

v1.22 版本停止提供下列已棄用的 API 版本

Webhook 資源

從 v1.22 開始，不再提供 MutatingWebhookConfiguration 和 ValidatingWebhookConfiguration 的 admissionregistration.k8s.io/v1beta1 API 版本。

  • 遷移 manifests 和 API client 以使用 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 版本。

  • 遷移 manifests 和 API client 以使用 apiextensions.k8s.io/v1 API 版本，此版本自 v1.16 起可用。
  • 所有現有持久化物件都可以透過新的 API 存取
  • 重大變更
    • spec.scope 不再預設為 Namespaced，必須明確指定
    • v1 中已移除 spec.version；請改用 spec.versions
    • v1 中已移除 spec.validation；請改用 spec.versions[*].schema
    • v1 中已移除 spec.subresources；請改用 spec.versions[*].subresources
    • v1 中已移除 spec.additionalPrinterColumns；請改用 spec.versions[*].additionalPrinterColumns
    • v1 中 spec.conversion.webhookClientConfig 已移至 spec.conversion.webhook.clientConfig
    • v1 中 spec.conversion.conversionReviewVersions 已移至 spec.conversion.webhook.conversionReviewVersions
    • 建立 v1 CustomResourceDefinition 物件時，現在需要 spec.versions[*].schema.openAPIV3Schema，且必須為結構化綱要
    • 建立 v1 CustomResourceDefinition 物件時，不允許使用 spec.preserveUnknownFields: true；必須在綱要定義中指定為 x-kubernetes-preserve-unknown-fields: true
    • 在 additionalPrinterColumns 項目中，v1 中 JSONPath 欄位已重新命名為 jsonPath (修正了 #66531)

APIService

從 v1.22 開始，不再提供 APIService 的 apiregistration.k8s.io/v1beta1 API 版本。

  • 遷移 manifests 和 API client 以使用 apiregistration.k8s.io/v1 API 版本，此版本自 v1.10 起可用。
  • 所有現有持久化物件都可以透過新的 API 存取
  • 無重大變更

TokenReview

從 v1.22 開始，不再提供 TokenReview 的 authentication.k8s.io/v1beta1 API 版本。

  • 遷移 manifests 和 API client 以使用 authentication.k8s.io/v1 API 版本，此版本自 v1.6 起可用。
  • 無重大變更

SubjectAccessReview 資源

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

  • 遷移 manifests 和 API client 以使用 authorization.k8s.io/v1 API 版本，此版本自 v1.6 起可用。
  • 重大變更
    • v1 中 spec.group 已重新命名為 spec.groups (修正了 #32709)

CertificateSigningRequest

從 v1.22 開始，不再提供 CertificateSigningRequest 的 certificates.k8s.io/v1beta1 API 版本。

  • 遷移 manifests 和 API client 以使用 certificates.k8s.io/v1 API 版本，此版本自 v1.19 起可用。
  • 所有現有持久化物件都可以透過新的 API 存取
  • certificates.k8s.io/v1 中的重大變更
    • 對於請求憑證的 API client
      • 現在 spec.signerName 為必填 (請參閱已知的 Kubernetes 簽署者)，且不允許透過 `certificates.k8s.io/v1` API 建立對 kubernetes.io/legacy-unknown 的請求
      • 現在 spec.usages 為必填，不得包含重複值，且僅能包含已知的用法
    • 對於核准或簽署憑證的 API client
      • status.conditions 不得包含重複的類型
      • 現在 status.conditions[*].status 為必填
      • status.certificate 必須為 PEM 編碼，且僅包含 CERTIFICATE 區塊

Lease

從 v1.22 開始，不再提供 Lease 的 coordination.k8s.io/v1beta1 API 版本。

  • 遷移 manifests 和 API client 以使用 coordination.k8s.io/v1 API 版本，此版本自 v1.14 起可用。
  • 所有現有持久化物件都可以透過新的 API 存取
  • 無重大變更

Ingress

從 v1.22 開始，不再提供 Ingress 的 extensions/v1beta1 和 networking.k8s.io/v1beta1 API 版本。

  • 遷移 manifests 和 API client 以使用 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 版本。

  • 遷移 manifests 和 API client 以使用 networking.k8s.io/v1 API 版本，此版本自 v1.19 起可用。
  • 所有現有持久化物件都可以透過新的 API 存取
  • 無重大變更

RBAC 資源

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

  • 遷移 manifests 和 API client 以使用 rbac.authorization.k8s.io/v1 API 版本，此版本自 v1.8 起可用。
  • 所有現有的持久化物件都可以透過新的 API 存取
  • 無重大變更

PriorityClass

從 v1.22 開始，不再提供 PriorityClass 的 scheduling.k8s.io/v1beta1 API 版本。

  • 遷移 manifests 和 API client 以使用 scheduling.k8s.io/v1 API 版本，此版本自 v1.14 起可用。
  • 所有現有持久化物件都可以透過新的 API 存取
  • 無重大變更

儲存資源

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

  • 遷移 manifests 和 API client 以使用 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 版本。

  • 遷移 manifests 和 API client 以使用 networking.k8s.io/v1 API 版本，此版本自 v1.8 起可用。
  • 所有現有持久化物件都可以透過新的 API 存取

DaemonSet

從 v1.16 開始，不再提供 DaemonSet 的 extensions/v1beta1 和 apps/v1beta2 API 版本。

  • 遷移 manifests 和 API client 以使用 apps/v1 API 版本，此版本自 v1.9 起可用。
  • 所有現有持久化物件都可以透過新的 API 存取
  • 重大變更
    • 已移除 spec.templateGeneration
    • 現在 spec.selector 為必填，且在建立後不可變更；使用現有的範本標籤作為選取器，以實現無縫升級
    • 現在 spec.updateStrategy.type 預設為 RollingUpdate (在 extensions/v1beta1 中的預設值為 OnDelete)

部署

從 v1.16 開始，不再提供 Deployment 的 extensions/v1beta1、apps/v1beta1 和 apps/v1beta2 API 版本。

  • 遷移 manifests 和 API client 以使用 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 版本。

  • 遷移 manifests 和 API client 以使用 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 版本。

  • 遷移 manifests 和 API client 以使用 apps/v1 API 版本，此版本自 v1.9 起可用。
  • 所有現有持久化物件都可以透過新的 API 存取
  • 重大變更
    • 現在 spec.selector 為必填，且在建立後不可變更；使用現有的範本標籤作為選取器，以實現無縫升級

PodSecurityPolicy

從 v1.16 開始，不再提供 PodSecurityPolicy 的 extensions/v1beta1 API 版本。

  • 遷移 manifests 和 API client 以使用 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 參考文件。

上次修改時間為 2024 年 3 月 17 日 凌晨 12:37 PST：更新 v1.25 和 v1.26 的 HorizontalPodAutoscaler 已棄用 API 遷移指南 (#45390) (f424d45142)