Kubernetes 1.22 の非推奨 API

このページでは、GKE バージョン 1.22 へのアップグレード用にクラスタを準備する方法について説明します。1.22 で削除された非推奨 API を呼び出している API クライアントを確認し、一般提供の API を使用するようにクライアントを更新できます。詳しくは、Kubernetes 非推奨 API 移行ガイドをご覧ください。

1.22 で削除された API

Kubernetes バージョン 1.22 の非推奨 API のほとんどは以前のベータ版 API で、その後、ベータ版（v1beta1）から一般提供（v1）に移行されました。一般提供の API では、長期の互換性が保証されます。非推奨のベータ版 API の代わりに、一般提供の API を使用してください。

既存のオブジェクトはすべて、一般提供の API を使用して操作できます。

Webhook リソース

MutatingWebhookConfiguration と ValidatingWebhookConfiguration のベータ版 API は、バージョン 1.22 で提供されなくなりました。

  • マニフェストと API クライアントを移行して、admissionregistration.k8s.io/v1 API バージョンを使用してください。

  • 一般提供の API バージョンの重要な変更点については、次の表をご覧ください。

    フィールド 変更
    webhooks[*].failurePolicy デフォルトが Ignore から Fail に変更されました。
    webhooks[*].matchPolicy デフォルトが Exact から Equivalent に変更されました。
    webhooks[*].timeoutSeconds デフォルトが 30s から 10s に変更されました。
    webhooks[*].sideEffects デフォルト値が削除され、フィールドに必須になりました。指定できるのは None と NoneOnDryRun のみです。
    webhooks[*].admissionReviewVersions デフォルト値が削除され、フィールドが必須になりました（AdmissionReview でサポートされているバージョンは v1 と v1beta1 です）。
    webhooks[*].name admissionregistration.k8s.io/v1 で作成されたオブジェクトのリスト内で一意にする必要があります。

CustomResourceDefinition

CustomResourceDefinition のベータ版 API バージョンは、バージョン 1.22 で提供されなくなりました。

  • マニフェストと API クライアントを移行して、apiextensions.k8s.io/v1 API バージョンを使用してください。

  • 一般提供の API バージョンの重要な変更点については、次の表をご覧ください。

    フィールド 変更
    spec.scope デフォルトは Namespaced ではなくなりました。値は明示的に指定する必要があります。
    spec.version 削除されました。spec.versions を代わりに使用してください。
    spec.validation 削除されました。spec.versions[*].schema を代わりに使用してください。
    spec.subresources 削除されました。spec.versions[*].subresources を代わりに使用してください。
    spec.additionalPrinterColumns 削除されました。spec.versions[*].additionalPrinterColumns を代わりに使用してください。
    spec.conversion.webhookClientConfig spec.conversion.webhook.clientConfig に移動しました。
    spec.conversion.conversionReviewVersions spec.conversion.webhook.conversionReviewVersions に移動しました。
    spec.versions[*].schema.openAPIV3Schema v1 CustomResourceDefinition オブジェクトの作成時に必須になりました。構造スキーマにする必要があります。
    spec.preserveUnknownFields v1 CustomResourceDefinition オブジェクトを作成する場合、値 true は使用できません。値は、スキーマ定義内で x-kubernetes-preserve-unknown-fields: true として指定する必要があります。
    additionalPrinterColumns additionalPrinterColumns 項目の JSONPath フィールド名が jsonPath に変更されました。

APIService

APIService のベータ版 API バージョンは、バージョン 1.22 で提供されなくなりました。マニフェストと API クライアントを移行して、apiregistration.k8s.io/v1 API バージョンを使用してください。

TokenReview

TokenReview のベータ版 API バージョンは、バージョン 1.22 で提供されなくなりました。マニフェストと API クライアントを移行して、authentication.k8s.io/v1 API バージョンを使用してください。

SubjectAccessReview リソース

LocalSubjectAccessReview、SelfSubjectAccessReview、SubjectAccessReview のベータ版 API バージョンは、バージョン 1.22 で提供されなくなりました。

  • マニフェストと API クライアントを移行して、authorization.k8s.io/v1 API バージョンを使用してください。

  • 一般提供の API バージョンの重要な変更点については、次の表をご覧ください。

    フィールド 変更
    spec.group 名前が spec.groups に変わりました。

CertificateSigningRequest

CertificateSigningRequest のベータ版 API バージョンは、バージョン 1.22 で提供されなくなりました。

  • マニフェストと API クライアントを移行して、certificates.k8s.io/v1 API バージョンを使用してください。

  • 一般提供の API バージョンの重要な変更点については、次の表をご覧ください。

    フィールド 変更
    spec.signerName 証明書をリクエストする API クライアントの場合、このフィールドは必須です（既知の Kubernetes 署名者を参照）。kubernetes.io/legacy-unknown に対するリクエストは、certificates.k8s.io/v1 API を介して作成することはできません。
    spec.usages 証明書をリクエストする API クライアントの場合、このフィールドは必須です。このフィールドに重複する値を含めることはできません。既知の使用方法のみを含める必要があります。
    status.conditions 証明書の承認または署名を行う API クライアントの場合、このフィールドに重複するタイプを含めることはできません。
    status.conditions[*].status 証明書の承認または署名を行う API クライアントの場合、このフィールドは必須です。
    status.certificate 証明書の承認または署名を行う API クライアントの場合、このフィールドは PEM でエンコードし、CERTIFICATE ブロックのみを含める必要があります。

Lease

Lease のベータ版 API バージョンは、バージョン 1.22 で提供されなくなりました。マニフェストと API クライアントを移行して、coordination.k8s.io/v1 API バージョンを使用してください。

Ingress（1.21 以前で作成されたクラスタでは 1.23 まで使用可能）

クラスタがバージョン 1.22 以降で作成された場合、Ingress のベータ版 API バージョン（extensions/v1beta1 と networking.k8s.io/v1beta1）は、バージョン 1.22 以降を実行している GKE クラスタには提供されなくなりました。

ただし、GKE バージョン 1.21 以前で作成され、パッチ バージョン 1.22.7-gke.300 以降で 1.22 にアップグレードされたクラスタの場合、クラスタがバージョン 1.23. にアップグレードされるまでベータ版 API バージョンを使用できます。これは、バージョン 1.22 のオープンソース Kubernetes から削除されるこれらの API バージョンの使用をやめ、クラスタを移行する時間を確保するための、古いクラスタに対する 1 回限りの例外です。

GKE バージョン 1.23 以降を実行しているクラスタでは、非推奨の Ingress ベータ版 API が提供されなくなります。これらの API バージョンを使用するマニフェストは適用できなくなります。以前に保持されたオブジェクトは引き続き機能し、1.23 にアップグレードする前と後で、新しい API バージョンを使用して表示および更新できます。

  • マニフェストと API クライアントを移行して、networking.k8s.io/v1 API バージョンを使用してください。

  • 一般提供の API バージョンの重要な変更点については、次の表をご覧ください。

    フィールド 変更
    spec.backend 名前が spec.defaultBackend に変わりました。
    backend serviceName 名前が service.name に変わりました。
    servicePort 数値バックエンドの servicePort フィールドの名前が service.port.number に変わりました。文字列バックエンドの servicePort フィールドの名前が service.port.name に変わりました。
    pathType 指定されたパスごとに必要になりました。値は Prefix、Exact、ImplementationSpecific のいずれかです。未定義の v1beta1 動作と一致させるには、ImplementationSpecific を使用します。

次のマニフェストは、v1 と v1beta1 で同じ Ingress を記述しています。

v1beta1 マニフェスト

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: example
spec:
  backend:
    serviceName: default-backend
    servicePort: 80
  rules:
  - http:
      paths:
      - path: /testpath
        backend:
          serviceName: test
          servicePort: 80

v1 マニフェスト

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example
spec:
  defaultBackend:
    service:
      name: default-backend
      port:
        number: 80
  rules:
  - http:
      paths:
      - path: /testpath
        pathType: ImplementationSpecific
        backend:
          service:
            name: test
            port:
              number: 80

Google Cloud Observability が有効になっているクラスタに対して次のクエリを使用すると、Ingress v1beta1 API にアクセスするクライアントを特定できます。

resource.type="k8s_cluster"
resource.labels.cluster_name="$CLUSTER_NAME"
protoPayload.authenticationInfo.principalEmail:("system:serviceaccount" OR "@")
protoPayload.request.apiVersion=("extensions/v1beta1" OR "networking.k8s.io/v1beta1")
protoPayload.request.kind="Ingress"
NOT ("kube-system")

IngressClass

IngressClass のベータ版 API バージョンは、バージョン 1.22 で提供されなくなりました。マニフェストと API クライアントを移行して、networking.k8s.io/v1 API バージョンを使用してください。

RBAC リソース

ClusterRole、ClusterRoleBinding、Role、RoleBinding のベータ版 API バージョンは、バージョン 1.22 で提供されなくなりました。マニフェストと API クライアントを移行して、rbac.authorization.k8s.io/v1 API バージョンを使用してください。

PriorityClass

PriorityClass のベータ版 API バージョンは、バージョン 1.22 で提供されなくなりました。マニフェストと API クライアントを移行して、scheduling.k8s.io/v1 API バージョンを使用してください。

Storage リソース

CSIDriver、CSINode、StorageClass、VolumeAttachment のベータ版 API バージョンは、バージョン 1.22 で提供されなくなりました。マニフェストと API クライアントを移行して、storage.k8s.io/v1 API バージョンを使用してください。

非推奨 API を使用しているクラスタを検索する

非推奨の API を使用しているクラスタは、非推奨に関する分析情報で確認できます。また、非推奨に関する分析情報では、どの API クライアントがクラスタ内で非推奨の API を呼び出しているのかなどの情報も表示できます。

監査ログを使用して、非推奨の API を呼び出しているクライアントを確認することもできます。

非推奨の API への書き込み呼び出しを行う API クライアントを特定する

Google Cloud Observability が有効になっているクラスタでは、次の管理アクティビティ監査ログクエリを使用すると、Google の管理外のユーザー エージェントによる非推奨の API の使用を確認できます。

resource.type="k8s_cluster"
labels."k8s.io/removed-release"="DEPRECATED_API_MINOR_VERSION"
protoPayload.authenticationInfo.principalEmail:("system:serviceaccount" OR "@")
protoPayload.authenticationInfo.principalEmail!~("system:serviceaccount:kube-system:")

DEPRECATED_API_MINOR_VERSION は、非推奨の API が削除されたマイナー バージョン（1.22 など）に置き換えます。

GKE クラスタに対して管理アクティビティ監査ログが自動的に有効になります。このクエリを使用して、非推奨の API への書き込み呼び出しを行っているユーザー エージェントがログに表示されます。

非推奨の API への読み取り呼び出しを行う API クライアントを特定する

デフォルトでは、監査ログには非推奨の API への書き込み呼び出しのみが表示されます。非推奨の API への読み取り呼び出しも表示するには、データアクセス監査ログを構成します。

手順に沿って、Google Cloud コンソールでデータアクセスの監査ログを構成します。Google Cloud コンソールで、Kubernetes Engine API を選択します。情報パネルの [ログタイプ] タブで、Admin Read と Data Read を選択します。

これらのログを有効にすると、元のクエリを使用して、非推奨の API に対する読み取り呼び出しと書き込み呼び出しの両方を確認できます。

サードパーティ コンポーネントのアップグレード

非推奨に関する分析情報に、クラスタ内の非推奨の API を呼び出すサードパーティ エージェントの結果が表示されます。

これらの分析情報を解決するには、次の手順を試してください。

  1. サードパーティ ソフトウェアのプロバイダに問い合わせて、最新バージョンを確認します。
  2. サードパーティ ソフトウェアを最新バージョンにアップグレードします。ソフトウェアをアップグレードできない場合は、GKE を非推奨の API を削除したバージョンにアップグレードするとサービスが停止するかどうかをテストする必要があります。

本番環境クラスタをアップグレードする前に、ステージング クラスタでこのアップグレードと GKE バージョンのアップグレードを行って、中断が発生しないかどうかモニタリングすることをおすすめします。

バージョン 1.22 へのアップグレードの準備

ユーザーは API オブジェクトを削除して再生成することは必要ありません。既存のすべての API オブジェクトは、すでに新しい API バージョンを使用して読み込み、更新できます。ただし、Kubernetes 1.22 にアップグレードする前に、クライアントとマニフェストを移行することをおすすめします。詳細については、非推奨 API の移行ガイドの「対処方法」をご覧ください。

非推奨化に関する分析情報と推奨事項を表示して、非推奨の Kubernetes 機能または API がクラスタで使用されているかどうかを判断できます。非推奨化に関する分析情報は、Kubernetes オブジェクトの構成ではなく、ユーザー エージェントによる非推奨 API への API 呼び出しを観測した結果に基づいています。

非推奨の影響を受けるクラスタを更新する

非推奨の影響を受けるクラスタをアップグレードする手順は、次のとおりです。

  1. 非推奨の API を使用しているユーザー エージェントは、非推奨化に関する分析情報またはログで確認できます。
  2. 非推奨の API を使用するユーザー エージェントを、サポート対象の API バージョンを使用するように更新します。
  3. 非推奨の API を呼び出すサードパーティ ソフトウェアを最新バージョンに更新します。
  4. 非推奨の API が使用不能になった場合の中断のリスクを軽減するために、本番環境クラスタをアップグレードする前に、テスト用クラスタをアップグレードしてテスト環境でアプリケーションをテストします。
  5. すべてのユーザー エージェントを更新すると、GKE は非推奨の API の使用が 30 日間観察されなくなるまで待機し、その後、自動アップグレードのブロックを解除します。自動アップグレードはリリース スケジュールに沿って行われます。
  6. 影響を受けるユーザー エージェントを更新できない場合は、別のテストクラスタをアップグレードして、アップグレードで中断が発生するかどうかを確認します。アップグレードで中断が発生しない場合は、クラスタを手動でアップグレードできます。

リソース

詳細については、以下の OSS Kubernetes ドキュメントをご覧ください。