GKE On-Prem API クライアントを使用して管理クラスタまたはユーザー クラスタをアップグレードする

このページでは、Google Cloud コンソールまたは Google Cloud CLI を使用して、GKE On-Prem API に登録されている Google Distributed Cloud 管理クラスタまたはユーザー クラスタをアップグレードする方法について説明します。Terraform を使用してユーザー クラスタを作成した場合は、Terraform を使用してユーザー クラスタをアップグレードできます。続行する前に、アップグレードのベスト プラクティスとクラスタ アップグレードのライフサイクルとステージでアップグレードの要件、ベスト プラクティス、アップグレード プロセスの詳細をご確認ください。

GKE On-Prem API とは

GKE On-Prem API は、Google Cloud がホストする API で、Terraform や標準の Google Cloud ツールを使用して、オンプレミス クラスタのライフサイクルを管理できます。GKE On-Prem API は、Google Cloud のインフラストラクチャで動作します。Terraform、Google Cloud コンソール、Google Cloud CLI は API のクライアントであり、API を使用してデータセンターのクラスタを作成、更新、アップグレード、削除します。標準クライアントを使用してクラスタを作成した場合、クラスタは GKE On-Prem API に登録されます。つまり、標準クライアントを使用してクラスタのライフサイクルを管理できます。（ただし、いくつか例外があります）。bmctl を使用してクラスタを作成した場合、GKE On-Prem API にクラスタを登録して、標準クライアントを使用できます。

始める前に

gcloud CLI を設定する

gcloud CLI または Terraform を使用してクラスタをアップグレードするには、次の操作を行います。

  1. 最新バージョンの gcloud CLI を使用していることを確認します。必要に応じて gcloud CLI コンポーネントを更新します。

    gcloud components update

IAM 要件

プロジェクト オーナーでない場合は、クラスタが作成された Google Cloud プロジェクトに対する roles/gkeonprem.admin Identity and Access Management ロールが付与されている必要があります。このロールに含まれる権限の詳細については、IAM のドキュメントで GKE On-Prem ロールの説明をご覧ください。

コンソールを使用してクラスタをアップグレードするには、少なくとも次のロールが必要です。

  • roles/container.viewer。このロールを使用すると、ユーザーはコンソールで GKE クラスタのページやその他のコンテナ リソースを表示できます。このロールに含まれる権限の詳細と、読み取り / 書き込み権限を持つロールの付与方法については、IAM のドキュメントで Kubernetes Engine ロールの説明をご覧ください。

  • roles/gkehub.viewer。このロールを使用すると、ユーザーはコンソールでクラスタを表示できます。このロールに含まれる権限の詳細と、読み取り / 書き込み権限を持つロールの付与方法については、IAM ドキュメントで GKE Hub ロールの説明をご覧ください。

バージョン要件

Google Distributed Cloud のリリース後、そのバージョンが GKE On-Prem API で利用可能になるまでに 7～10 日ほどかかります。

同じマイナー リリースか、その次のマイナー リリースに含まれるバージョンには直接アップグレードできます。たとえば、1.29.100 から 1.29.200、または 1.28.100 から 1.29.200 にアップグレードできます。インストールされているバージョンから、2 つ以上後のマイナー リリースのバージョンにアップグレードすることはできません。

管理クラスタは、同じマイナー バージョンまたは以前のマイナー バージョンのユーザー クラスタを管理できます。マネージド ユーザー クラスタは、管理クラスタより 1 つ前のマイナー バージョン以降でなければなりません。そのため、管理クラスタを新しいマイナー バージョンにアップグレードする前に、すべてのマネージド ユーザー クラスタが管理クラスタと同じマイナー バージョンであることを確認してください。

管理クラスタをアップグレードする

コンソール

  1. コンソールで、Google Kubernetes Engine クラスタの概要ページに移動します。

    GKE クラスタに移動

  2. Google Cloud プロジェクトを選択して、アップグレードするクラスタを選択します。

  3. [詳細] パネルで、[詳細] をクリックします。

  4. [クラスタの基本] セクションで、[ アップグレード] をクリックします。

  5. [ターゲット バージョンの選択] リストで、アップグレード後のバージョンを選択します。最新のパッチ バージョンにアップグレードすることをおすすめします。

  6. [アップグレード] をクリックします。

クラスタがアップグレードされる前にプリフライト チェックが実行され、クラスタのステータスとノードの健全性が検証されます。プリフライト チェックに合格すると、管理クラスタがアップグレードされます。クラスタのサイズによっては、アップグレードが完了するまでに 30 分以上かかります。

アップグレードのステータスを表示するには、[クラスタの詳細] タブの [詳細を表示] をクリックします。

gcloud CLI

  1. 必要に応じて、プロジェクトに登録されているすべての管理クラスタを一覧表示して、クラスタ名とリージョンを確認します。

    gcloud container bare-metal admin-clusters list \
  --project=PROJECT_ID \
  --location=-

    • PROJECT_ID は、クラスタがメンバーであるフリート ホスト プロジェクトの ID に置き換えます。bmctl を使用してクラスタを作成した場合、これはクラスタ構成ファイルの gkeConnect.projectID フィールドのプロジェクト ID です。

    • --location=- に設定すると、すべてのリージョンのクラスタがすべて一覧表示されます。リストを絞り込む場合は、--location を特定のリージョンに設定します。

    PERMISSION_DENIED エラーが発生した場合は、入力したプロジェクト ID を再確認してください。プロジェクト ID が正しい場合は、gcloud auth login を実行して、プロジェクトにアクセスできるアカウントで Google Cloud CLI にログインします。

  2. アップグレード先として使用可能なバージョンのリストを取得します。

    gcloud container bare-metal admin-clusters query-version-config \
  --admin-cluster=ADMIN_CLUSTER_NAME \
  --project=PROJECT_ID \
  --location=REGION

    次のように置き換えます。

    • ADMIN_CLUSTER_NAME: 管理クラスタの名前。

    • PROJECT_ID: クラスタがメンバーであるフリート ホスト プロジェクトの ID。

    • REGION: GKE On-Prem API が実行され、クラスタ メタデータを保存する Google Cloud リージョン。

  3. 管理クラスタをアップグレードします。

    gcloud container bare-metal admin-clusters update ADMIN_CLUSTER_NAME \
  --project=PROJECT_ID \
  --location=REGION \
  --version=VERSION

    VERSION は、アップグレード後の Google Distributed Cloud のバージョンに置き換えます。前のコマンドの出力にあるバージョンを指定します。最新のパッチ バージョンにアップグレードすることをおすすめします。

    このコマンドからの出力は、次のようになります。

    Waiting for operation [projects/example-project-12345/locations/us-west1/operations/operation-1679543737105-5f7893fd5bae9-942b3f97-75e59179] to complete.

    この出力例では、operation-1679543737105-5f7893fd5bae9-942b3f97-75e59179 という文字列は長時間実行オペレーションの OPERATION_ID です。

    オペレーションのステータスを確認するには、出力から OPERATION_ID を次のコマンドにコピーします。別のターミナル ウィンドウを開き、コマンドを実行します。

    gcloud container bare-metal operations describe OPERATION_ID \
  --project=PROJECT_ID \
  --location=REGION

クラスタのサイズによっては、アップグレードが完了するまでに 30 分以上かかります。クラスタがアップグレードされている間、上記のコマンドを繰り返し実行することで現在のステータスを取得できます。

アップグレードが完了すると、gcloud ... update コマンドを実行したターミナル ウィンドウに次のようなメッセージが表示されます。

Updated Anthos on bare metal Admin Cluster [https://gkeonprem.googleapis.com/v1/projects/example-project-1234/locations/us-central1/bareMetalAdminClusters/abm-admin-cluster].
NAME               LOCATION     VERSION     MEMBERSHIP         STATE
abm-admin-cluster  us-central1  1.29.400-gke.86      abm-admin-cluster  RUNNING

フィールドとフラグの詳細については、gcloud container bare-metal admin-clusters リファレンスをご覧ください。

ユーザー クラスタをアップグレードする

コンソール

  1. コンソールで、Google Kubernetes Engine クラスタの概要ページに移動します。

    GKE クラスタに移動

  2. Google Cloud プロジェクトを選択して、アップグレードするクラスタを選択します。

  3. [詳細] パネルで、[詳細] をクリックします。

  4. [クラスタの基本] セクションで、[ アップグレード] をクリックします。

  5. [ターゲット バージョンの選択] リストで、アップグレード後のバージョンを選択します。

  6. [アップグレード] をクリックします。

クラスタがアップグレードされる前にプリフライト チェックが実行され、クラスタのステータスとノードの健全性が検証されます。プリフライト チェックに合格すると、ユーザー クラスタがアップグレードされます。クラスタのサイズによっては、アップグレードが完了するまでに 30 分以上かかります。

アップグレードのステータスを表示するには、[クラスタの詳細] タブの [詳細を表示] をクリックします。

gcloud CLI

  1. 必要に応じて、プロジェクトに登録されているすべてのユーザー クラスタを一覧表示して、クラスタ名とリージョンを確認します。

    gcloud container bare-metal clusters list \
  --project=PROJECT_ID \
  --location=-

    • PROJECT_ID は、クラスタがメンバーであるフリート ホスト プロジェクトの ID に置き換えます。bmctl を使用してクラスタを作成した場合、これはクラスタ構成ファイルの gkeConnect.projectID フィールドのプロジェクト ID です。

    • --location=- に設定すると、すべてのリージョンのクラスタがすべて一覧表示されます。リストを絞り込む場合は、--location を特定のリージョンに設定します。

    コマンドの出力は、次のようになります。

    NAME              LOCATION     VERSION  ADMIN_CLUSTER      STATE
abm-user-cluster  us-central1  1.29.400-gke.86   abm-admin-cluster  RUNNING

    PERMISSION_DENIED エラーが発生した場合は、入力したプロジェクト ID を再確認してください。プロジェクト ID が正しい場合は、gcloud auth login を実行して、プロジェクトにアクセスできるアカウントで Google Cloud CLI にログインします。

  2. アップグレード先として使用可能なバージョンのリストを取得します。

    gcloud container bare-metal clusters query-version-config \
  --cluster=USER_CLUSTER_NAME \
  --project=PROJECT_ID \
  --location=REGION

    次のように置き換えます。

    • USER_CLUSTER_NAME: アップグレードするユーザー クラスタの名前。

    • PROJECT_ID: クラスタがメンバーであるフリート ホスト プロジェクトの ID。

    • REGION: GKE On-Prem API が実行され、クラスタ メタデータを保存する Google Cloud リージョン。

    コマンドの出力は、次のようになります。

    versions:
- hasDependencies: true
version: 1.15.2
- hasDependencies: true
version: 1.15.1
- hasDependencies: true
version: 1.15.0
- version: 1.14.6

    - hasDependencies: true に表示されていないバージョンを選択します。この例では、ユーザー クラスタのアップグレードで使用できるバージョンは、1.14.6 のみです。

  3. 次のようにユーザー クラスタをアップグレードします。

    gcloud container bare-metal clusters update USER_CLUSTER_NAME \
  --project=PROJECT_ID \
  --location=REGION \
  --version=VERSION

    VERSION は、アップグレード後の Google Distributed Cloud のバージョンに置き換えます。前のコマンドの出力にあるバージョンを指定します。最新のパッチ バージョンにアップグレードすることをおすすめします。

    このコマンドからの出力は、次のようになります。

    Waiting for operation [projects/example-project-12345/locations/us-west1/operations/operation-1679543737105-5f7893fd5bae9-942b3f97-75e59179] to complete.

    この出力例では、operation-1679543737105-5f7893fd5bae9-942b3f97-75e59179 という文字列は長時間実行オペレーションの OPERATION_ID です。

    オペレーションのステータスを確認するには、出力から OPERATION_ID を次のコマンドにコピーします。別のターミナル ウィンドウを開き、コマンドを実行します。

    gcloud container bare-metal operations describe OPERATION_ID \
  --project=PROJECT_ID \
  --location=REGION

クラスタのサイズによっては、アップグレードが完了するまでに 30 分以上かかります。クラスタがアップグレードされている間、上記のコマンドを繰り返し実行することで現在のステータスを取得できます。

フィールドとフラグの詳細については、gcloud container bare-metal clusters リファレンスをご覧ください。

Terraform

Terraform を使用してクラスタをアップグレードするには、クラスタの作成に使用した Terraform 構成を使用します。

  1. Terraform 構成ファイルが配置されているディレクトリに移動します。

  2. アップグレード先として使用可能なバージョンのリストを取得します。

    gcloud container bare-metal clusters query-version-config \
  --cluster=USER_CLUSTER_NAME \
  --project=PROJECT_ID \
  --location=REGION

    次のように置き換えます。

    • USER_CLUSTER_NAME: アップグレードするユーザー クラスタの名前。

    • PROJECT_ID: ユーザー クラスタがメンバーであるフリート ホスト プロジェクトの ID。

    • REGION: GKE On-Prem API が稼働しメタデータを保存する Google Cloud リージョン。

    PERMISSION_DENIED エラーが発生した場合は、入力したプロジェクト ID を再確認してください。プロジェクト ID が正しい場合は、gcloud auth login を実行して、プロジェクトにアクセスできるアカウントで Google Cloud CLI にログインします。

  3. Terraform 構成で、bare_metal_version をアップグレード後の Google Distributed Cloud のバージョンに変更します。前のコマンドの出力にあるバージョンを指定します。最新のパッチ バージョンにアップグレードすることをおすすめします。

  4. Terraform プランを初期化して作成します。

    terraform init

    Terraform によって、Google Cloud プロバイダなどの必要なライブラリがインストールされます。

  5. 構成を確認し、必要に応じて変更を加えます。

    terraform plan

  6. Terraform プランを適用して、ユーザー クラスタを作成します。

    terraform apply

google_gkeonprem_bare_metal_cluster リソースの詳細については、リファレンス ドキュメントをご覧ください。