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 プロジェクトで Identity and Access Management のロール roles/gkeonprem.admin を付与されている必要があります。このロールに含まれる権限の詳細については、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. [Upgrade] をクリックします。

クラスタがアップグレードされる前にプリフライト チェックが実行され、クラスタのステータスとノードの健全性が検証されます。プリフライト チェックに合格すると、管理クラスタがアップグレードされます。クラスタのサイズによっては、アップグレードが完了するまでに 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.100-gke.251      abm-admin-cluster  RUNNING

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

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

コンソール

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

    GKE クラスタに移動

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

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

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

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

  6. [Upgrade] をクリックします。

クラスタがアップグレードされる前にプリフライト チェックが実行され、クラスタのステータスとノードの健全性が検証されます。プリフライト チェックに合格すると、ユーザー クラスタがアップグレードされます。クラスタのサイズによっては、アップグレードが完了するまでに 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.100-gke.251   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 リソースの詳細については、リファレンス ドキュメントをご覧ください。