GKE on VMware のアップグレード

このページでは、GKE on VMware をアップグレードする方法について説明します。このページでは、管理ワークステーション、ユーザー クラスタ、管理クラスタをアップグレードする手順について説明します。ユーザー クラスタについては、コントロール プレーンとノードプールを同時にアップグレードする、または個別にアップグレードする手順を説明します。

続行する前に、次のドキュメントを確認することをおすすめします。

  • アップグレードの概要
    このドキュメントでは、その他の点として、サポートされているバージョン スキューとバージョン ルール(1.28 以降で変更された)について説明します。

  • アップグレードのベスト プラクティス
    このドキュメントでは、クラスタのアップグレードに関するチェックリストとベスト プラクティスについて説明します。

Google API と IAM の要件

クラスタをバージョン 1.28 以降にアップグレードするには、kubernetesmetadata.googleapis.com を有効にして、kubernetesmetadata.publisher IAM ロールを logging-monitoring サービス アカウントに付与する必要があります。Cloud Monitoring を使用するために、これらの変更が必要です。

  1. kubernetesmetadata.googleapis.com の有効化:

    gcloud services enable --project PROJECT_ID  \
        kubernetesmetadata.googleapis.com
    

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

  2. Google API や他のアドレスからのトラフィックがプロキシ サーバーを通過できるよう組織が許可リストを設定している場合は、kubernetesmetadata.googleapis.com を許可リストに追加します。

  3. logging-monitoring サービス アカウントに kubernetesmetadata.publisher ロールを付与します。

    gcloud projects add-iam-policy-binding PROJECT_ID \
      --member "serviceAccount:SERVICE_ACCOUNT_EMAIL" \
      --role "roles/kubernetesmetadata.publisher"
    

    SERVICE_ACCOUNT_EMAIL を、logging-monitoring サービス アカウントのメールアドレスに置き換えます。

ユーザー クラスタのアップグレードに必要な IAM の要件

ユーザー クラスタのアップグレードに gkectl を使用する場合は、このセクションをスキップしてください。

ユーザー クラスタのアップグレードに Google Cloud コンソール、Google Cloud CLI、または Terraform を使用し、かつプロジェクト オーナーでない場合は、クラスタが作成された 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 のロールをご覧ください。

管理ワークステーションをアップグレードする

gkectl を使用してユーザー クラスタをアップグレードする予定の場合は、管理ワークステーションをアップグレードする必要があります。

コンソール、gcloud CLI、または Terraform を使用してユーザー クラスタをアップグレードする場合は、さしあたり管理ワークステーションのアップグレードをスキップできます。しかし、管理クラスタのアップグレードは、gkectl のみがサポートしているため、管理クラスタをアップグレードする準備ができたら、管理ワークステーションをアップグレードする必要があります。

必要なファイルを見つける

管理ワークステーションを作成する前に、gkeadm create config によって生成された管理ワークステーションの構成ファイルに入力しました。このファイルのデフォルト名は admin-ws-config.yaml です。

また、ワークステーションにも情報ファイルがあります。このファイルのデフォルト名は、管理ワークステーションの名前と同じです。

管理ワークステーションの構成ファイルと情報ファイルを探します。アップグレード手順を実行するには、それらが必要です。これらのファイルが現在のディレクトリにあり、デフォルトの名前が使われている場合は、アップグレード コマンドを実行するときに名前を指定する必要はありません。これらのファイルが別のディレクトリにある場合や、ファイル名を変更した場合は、--config フラグと --info-file フラグを使用して指定します。

出力情報ファイルがない場合は再作成できます。情報ファイルがない場合は再作成するをご覧ください。

管理ワークステーションをアップグレードするには:

  1. gkeadm をダウンロードする

    gkeadm upgrade gkeadm --target-version TARGET_VERSION
    

    TARGET_VERSION は、アップグレードのターゲット バージョンに置き換えます。X.Y.Z-gke.N. の形式で完全なバージョン番号を指定する必要があります。GKE on VMware バージョンの一覧については、バージョン履歴をご覧ください。

  2. 管理ワークステーションをアップグレードする

    gkeadm upgrade admin-workstation --config AW_CONFIG_FILE \
        --info-file INFO_FILE
    

    以下を置き換えます。

    • AW_CONFIG_FILE: 管理ワークステーションの構成ファイルのパス。ファイルが現在のディレクトリにあり、名前が admin-ws-config.yaml の場合、このフラグを省略できます。

    • INFO_FILE: 情報ファイルのパス。ファイルが現在のディレクトリにある場合は、このフラグを省略できます。このファイルのデフォルト名は、管理ワークステーションの名前と同じです。

    上記のコマンドによって、以下のタスクが実行されます。

    • 現在の管理ワークステーションのホーム ディレクトリにあるすべてのファイルをバックアップします。たとえば、次のようなものが挙げられます。

      • 管理クラスタの構成ファイル。デフォルト名は admin-cluster.yaml です。
      • ユーザー クラスタの構成ファイル。デフォルト名は user-cluster.yaml です。
      • 管理クラスタとユーザー クラスタの kubeconfig ファイル。
      • vCenter サーバーのルート証明書(このファイルにはオーナーの読み取り権限とオーナーの書き込み権限が必要)。
      • コンポーネント アクセス サービス アカウントの JSON キーファイル(このファイルにはオーナーの読み取り権限とオーナーの書き込み権限が必要)。
      • connect-register、logging-monitoring サービス アカウントの JSON キーファイル。
    • 新しい管理ワークステーションを作成し、すべてのバックアップ ファイルを新しい管理ワークステーションにコピーします。

    • 古い管理ワークステーションを削除します。

クラスタのアップグレードで利用可能なバージョンを確認する

次のコマンドを実行して、アップグレード可能なバージョンを確認します。

gkectl version --kubeconfig ADMIN_CLUSTER_KUBECONFIG

出力に、現在のバージョンとアップグレード可能なバージョンが表示されます。

アップグレードにコンソール、gcloud CLI、または Terraform を使用する場合、すべての Google Cloud リージョンの GKE On-Prem API でバージョンが使用可能になるまでリリースから約 7~10 日かかります。コンソールには、ユーザー クラスタのアップグレードで利用可能なバージョンのみが表示されます。gcloud CLI または Terraform を使用してユーザー クラスタをアップグレードする手順には、アップグレードで利用可能なバージョンを取得する gcloud container vmware clusters query-version-config を実行するステップが含まれています。

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

ユーザー クラスタは、gkectl、コンソール、gcloud CLI、または Terraform を使用してアップグレードできます。使用するツールの選定については、ユーザー クラスタをアップグレードするツールを選択するをご覧ください。

gkectl

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

管理ワークステーションで次の手順を行います。

  1. gkectl prepare を実行して、OS イメージを vSphere にインポートします。

    gkectl prepare \
      --bundle-path /var/lib/gke/bundles/gke-onprem-vsphere-TARGET_VERSION.tgz \
      --kubeconfig ADMIN_CLUSTER_KUBECONFIG
    
  2. クラスタに Windows ノードプールがある場合は、gkectl prepare windows を実行して、ノードプールの osImage フィールドを更新します。詳しい手順については、Windows ノードプールを含むユーザー クラスタをアップグレードするをご覧ください。

  3. ユーザー クラスタの構成ファイルで、gkeOnPremVersion をアップグレードのターゲット バージョンに設定します。

  4. Ubuntu ノードプールと COS ノードプールのみ: アップグレードするノードプールを指定します。コントロール プレーンとは別にノードプールをアップグレードすることは、Ubuntu ノードプールと COS ノードプールではサポートされていますが、Windows ノードプールではサポートされていません。

    ユーザー クラスタの構成ファイルで、次のようにアップグレードするノードプールを指定します。

    • アップグレードするノードプールごとに、nodePools.nodePool[i].gkeOnPremVersion フィールドを削除するか、空の文字列に設定します。

    • アップグレードしないノードプールごとに、nodePools.nodePool[i].gkeOnPremVersion を現在のバージョンに設定します。

    たとえば、ユーザー クラスタがバージョン 1.15.5-gke.41 で、pool-1pool-2 の 2 つのノードプールがあるとします。また、コントロール プレーンと pool-1 は 1.16.3-gke.45 にアップグレードするが、pool-2 はバージョン 1.15.5-gke.41 のままにするとします。ユーザー クラスタ構成ファイルの次の部分は、この例を指定する方法を示しています。

    gkeOnPremVersion: 1.16.3-gke.45
    
    nodePools:
    - name: pool-1
      gkeOnPremVersion: ""
      cpus: 4
      memoryMB: 8192
      replicas: 3
      osImageType: ubuntu_containerd
    - name: pool-2
      gkeOnPremVersion: 1.15.5-gke.41
      cpus: 4
      memoryMB: 8192
      replicas: 5
      osImageType: ubuntu_containerd
    

実行 gkectl upgrade cluster

gkectl upgrade cluster コマンドには 2 つのバリエーションがあります。

  • 非同期: (推奨)
    非同期のバリエーションでは、コマンドはアップグレードを開始して最後まで進みます。アップグレードの期間全体を通して、コマンドの出力を監視する必要はありません。そうする代わりに、gkectl list clustersgkectl describe clusters を実行して、アップグレードの進行状況を定期的に確認できます。非同期のバリエーションを使用するには、コマンドに --async フラグを追加します。

  • 同期:
    同期のバリエーションでは、アップグレードが進むと、gkectl upgrade cluster コマンドにより管理ワークステーションにステータス メッセージが出力されます。

非同期アップグレード

  1. 管理ワークステーションで、非同期アップグレードを開始します。

    gkectl upgrade cluster \
      --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
      --config USER_CLUSTER_CONFIG \
      --async
    

    上記のコマンドは完了し、アップグレードの進行中も管理ワークステーションを引き続き使用できます。

  2. アップグレードのステータスを確認するには:

    gkectl list clusters --kubeconfig ADMIN_CLUSTER_KUBECONFIG
    

    出力には、クラスタ STATE の値が表示されます。クラスタがまだアップグレード中である場合、STATE の値は UPGRADING です。次に例を示します。

    NAMESPACE             NAME    READY   STATE       AGE   VERSION
    my-uc-gkeonprem-mgmt  my-uc   False   UPGRADING   9h    1.28.0-gke.1
    

    STATE の想定される値は、PROVISIONINGUPGRADINGDELETINGUPDATINGRUNNINGRECONCILINGERRORUNKNOWN です。

  3. アップグレードの進行状況とクラスタ イベントの詳細を確認するには:

    gkectl describe clusters --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
      --cluster USER_CLUSTER_NAME -v 5
    

    出力には、指定したユーザー クラスタの OnPremUserCluster カスタム リソースが表示されます。これには、クラスタのステータス、条件、イベントが含まれます。

    次のような重要なアップグレード フェーズの開始と終了のイベントを記録します。

    • ControlPlaneUpgrade
    • MasterNodeUpgrade
    • AddonsUpgrade
    • NodePoolsUpgrade

    出力例:

    Events:
    Type    Reason                      Age    From                            Message
    ----     ------                     ----   ----                            -------
    Normal  NodePoolsUpgradeStarted     22m    onprem-user-cluster-controller  Creating or updating node pools: pool-2: Creating or updating node pool
    Normal  AddonsUpgradeStarted        22m    onprem-user-cluster-controller  Creating or updating addon workloads
    Normal  ControlPlaneUpgradeStarted  25m    onprem-user-cluster-controller  Creating or updating cluster control plane workloads: deploying user-kube-apiserver-base, ...: 14/15 pods are ready
    Normal  ControlPlaneUpgradeFinished 23m    onprem-user-cluster-controller  Control plane is running
    
  4. アップグレードが完了すると、gkectl list clusters によって RUNNINGSTATUS が表示されます。

    NAMESPACE             NAME    READY   STATE     AGE     VERSION
    my-uc-gkeonprem-mgmt  my-uc   True    RUNNING   9h      1.28.0-gke.1
    

    また、アップグレードが完了すると、gkectl describe clusters によって Status の下に LastGKEOnPremVersion フィールドが表示されます。次に例を示します。

    Status:
    Cluster State:  RUNNING
    LastGKEOnOremVersion:  1.28.0-gke.1
    

非同期アップグレードのトラブルシューティング

非同期アップグレードの場合、タイムアウト時間はクラスタ内のノードの数に基づきます。アップグレードがタイムアウト時間よりも長くかかる場合、アップグレード オペレーションがタイムアウトしたことを示すイベントが発生し、クラスタの状態が UPGRADING から ERROR に変更されます。なお、ERROR 状態は、アップグレードに想定より長い時間がかかっているが、終了されていないことを意味します。コントローラは整合を続行し、オペレーションを再試行し続けます。

タイムアウトは通常、PodDisruptionBudget(PDB)によってデッドロックが発生した結果生じます。この場合、Pod を古いノードから削除できず、古いノードをドレインできません。Pod の強制排除に 10 分超を要する場合、OnPremUserCluster オブジェクトにイベントが書き込まれます。イベントをキャプチャするには、gkectl describe clusters を実行します。次に、PDB を調整して、ノードをドレインできます。その後は、アップグレードを続行でき、最終的に完了します。

イベントの例:

Warning  PodEvictionTooLong  96s (x2 over 4m7s)  onprem-user-cluster-controller
Waiting too long(>10m0.00000003s) for (kube-system/coredns-856d6dbfdf-dl6nz) eviction.

また、アップグレードがブロックされている場合や失敗した場合は、gkectl diagnose を実行してクラスタの一般的な問題を確認できます。その結果に基づいて、手動で修正を行うか、Anthos サポートチームにその後のサポートについて連絡するかを決定できます。

同期アップグレード

gkectl upgrade コマンドは、プリフライト チェックを実行します。プリフライト チェックが不合格の場合、コマンドはブロックされます。障害を修正するか、--skip-preflight-check-blocking フラグを使用する必要があります。重大な不備がないことが確実な場合にのみ、プリフライト チェックをスキップしてください。

管理ワークステーションで次の手順を行います。

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

    gkectl upgrade cluster \
      --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
      --config USER_CLUSTER_CONFIG_FILE
    
  2. バージョン 1.14.0 以降にアップグレードすると、ユーザー クラスタ用に新しい kubeconfig ファイルが生成され、既存のファイルは上書きされます。ファイル内のクラスタの詳細を表示するには、次のコマンドを実行します。

    kubectl config view --kubeconfig USER_CLUSTER_KUBECONFIG

追加のノードプールをアップグレードする

ユーザー クラスタのコントロール プレーンのみをアップグレードした場合や、すべてのノードプールではなく、コントロール プレーンをアップグレードした場合は、次の手順でノードプールをアップグレードします。

  1. ユーザー クラスタの構成ファイルを編集します。アップグレードするノードプールごとに、次の例のように nodePools.nodePool[i].gkeOnPremVersion フィールドを削除するか、空の文字列に設定します。

    gkeOnPremVersion: 1.16.3-gke.45
    
    nodePools:
    - name: pool-1
      gkeOnPremVersion: ""
      cpus: 4
      memoryMB: 8192
      replicas: 3
      osImageType: ubuntu_containerd
    - name: pool-2
      gkeOnPremVersion: ""
      cpus: 4
      memoryMB: 8192
      replicas: 5
      osImageType: ubuntu_containerd
    
  2. gkectl update cluster を実行して変更を適用します。

    gkectl update cluster --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
      --config USER_CLUSTER_CONFIG
    

    以下を置き換えます。

    • ADMIN_CLUSTER_KUBECONFIG: 管理クラスタの kubeconfig ファイルのパス

    • USER_CLUSTER_CONFIG: ユーザー クラスタの構成ファイルのパス

ノードプールのアップグレード後に問題が発生した場合は、以前のバージョンにロールバックできます。詳細については、ノードプールのアップグレード後のロールバックをご覧ください。

アップグレードを再開する

ユーザー クラスタのアップグレードが中断された場合は、--skip-validation-all フラグを指定して同じアップグレード コマンドを使用すると、ユーザー クラスタのアップグレードを再開できます。

gkectl upgrade cluster \
  --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
  --config USER_CLUSTER_CONFIG_FILE \
  --skip-validation-all

コンソール

ユーザー クラスタをアップグレードするには、管理クラスタに変更を加える必要があります。コンソールでは、自動的に次の処理が行われます。

  • まだ登録されていない場合は、管理クラスタを GKE On-Prem API に登録します。

  • コンポーネントのバンドルをダウンロードして管理クラスタにデプロイします。コンポーネントのバージョンが、アップグレードに指定したバージョンと一致します。これらのコンポーネントを使用すると、管理クラスタはそのバージョンのユーザー クラスタを管理できます。

ユーザー クラスタをアップグレードするには、次のコマンドを実行します。

  1. コンソールで [GKE Enterprise クラスタ] ページに移動します。

    GKE Enterprise の [クラスタ] ページに移動

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

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

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

  5. [ターゲット バージョンを選択] リストで、アップグレード後のバージョンを選択します。キュレートされたリストには、最新のパッチリリースのみが含まれます。

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

クラスタがアップグレードされる前に、プリフライト チェックが実行され、クラスタのステータスとノードの健全性が検証されます。プリフライト チェックに合格すると、ユーザー クラスタがアップグレードされます。アップグレードが完了するまでに約 30 分を要します。

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

gcloud CLI

ユーザー クラスタをアップグレードするには、管理クラスタに変更を加える必要があります。gcloud container vmware clusters upgrade コマンドは、次の処理を自動的に行います。

  • まだ登録されていない場合は、管理クラスタを GKE On-Prem API に登録します。

  • コンポーネントのバンドルをダウンロードして管理クラスタにデプロイします。コンポーネントのバージョンが、アップグレードに指定したバージョンと一致します。これらのコンポーネントを使用すると、管理クラスタはそのバージョンのユーザー クラスタを管理できます。

ユーザー クラスタをアップグレードするには、次のコマンドを実行します。

  1. Google Cloud CLI のコンポーネントを更新します。

    gcloud components update
    
  2. Ubuntu ノードプールと COS ノードプールのみ: ユーザー クラスタのコントロール プレーンのみをアップグレードし、すべてのノードプールを現在のバージョンのままにする場合は、クラスタのアップグレード ポリシーを変更します。

    gcloud container vmware clusters update USER_CLUSTER_NAME \
      --project=PROJECT_ID \
      --location=REGION \
      --upgrade-policy control-plane-only=True
    

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

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

    • PROJECT_ID: ユーザー クラスタがメンバーであるフリート ホスト プロジェクトの ID。これは、クラスタの作成時に指定したプロジェクトです。gkectl を使用してクラスタを作成した場合、これはクラスタ構成ファイルの gkeConnect.projectID フィールドのプロジェクト ID です。

    • REGION: GKE On-Prem API が稼働しメタデータを保存する Google Cloud リージョン。GKE On-Prem API クライアントを使用してクラスタを作成した場合、これはクラスタの作成時に選択したリージョンです。gkectl を使用してクラスタを作成した場合、これは GKE On-Prem API にクラスタを登録したときに指定したリージョンです。

  3. アップグレード可能なバージョンのリストを取得します。

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

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

    versions:
    - version: 1.16.3-gke.45
    - version: 1.16.2-gke.28
    - version: 1.16.1-gke.45
    - version: 1.16.0-gke.669
    - version: 1.15.6-gke.25
    - version: 1.15.5-gke.41
    
    An Anthos version must be made available on the admin cluster ahead of the user
    cluster creation or upgrade. Versions annotated with isInstalled=true are
    installed on the admin cluster for the purpose of user cluster creation or
    upgrade whereas other version are released and will be available for upgrade
    once dependencies are resolved.
    
    To install the version in the admin cluster, run:
    $ gcloud container vmware admin-clusters update my-admin-cluster --required-platform-version=VERSION
    

    バージョン一覧の後のメッセージは無視してかまいません。アップグレード先のバージョンが管理クラスタにインストールされているかどうかは関係ありません。upgrade コマンドは、upgrade コマンドで指定したバージョンと一致するコンポーネントのバンドルをダウンロードしてデプロイします。

  4. クラスタをアップグレードします。 update コマンドを実行してアップグレード ポリシーを control-plane-only=True に変更した場合は、クラスタのコントロール プレーンのみがアップグレードされます。それ以外の場合、クラスタのコントロール プレーンとすべてのノードプールがアップグレードされます。

    gcloud container vmware clusters upgrade USER_CLUSTER_NAME \
      --project=PROJECT_ID \
      --location=REGION \
      --version=VERSION
    

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

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

    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 です。 オペレーションのステータスを確認するには、別のターミナル ウィンドウで次のコマンドを実行します。

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

ノードプールをアップグレードする

ユーザー クラスタのコントロール プレーンのみをアップグレードする場合は、ユーザー クラスタのコントロール プレーンをアップグレードした後に、次の手順に沿ってノードプールをアップグレードします。

  1. ユーザー クラスタにあるノードプールのリストを取得します。

    gcloud container vmware node-pools list
      --cluster=USER_CLUSTER_NAME  \
      --project=PROJECT_ID \
      --location=REGION
    
  2. アップグレードするノードプールごとに、次のコマンドを実行します。

    gcloud container vmware node-pools update NODE_POOL_NAME \
      --cluster=USER_CLUSTER_NAME  \
      --project=PROJECT_ID \
      --location=REGION \
      --version=VERSION
    

Terraform

  1. Google Cloud CLI のコンポーネントを更新します。

    gcloud components update
    
  2. まだ行っていない場合は、GKE On-Prem API に管理クラスタを登録します。クラスタが GKE On-Prem API に登録された後は、この手順を繰り返す必要はありません。

  3. アップグレード可能なバージョンのリストを取得します。

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

    以下を置き換えます。

    • USER_CLUSTER_NAME: ユーザー クラスタの名前。

    • PROJECT_ID: ユーザー クラスタがメンバーであるフリート プロジェクトの ID。これは、クラスタの作成時に指定したプロジェクトです。gkectl を使用してクラスタを作成した場合、これはクラスタ構成ファイルの gkeConnect.projectID フィールドのプロジェクト ID です。

    • REGION: GKE On-Prem API が稼働しメタデータを保存する Google Cloud リージョン。ユーザー クラスタの作成に使用した main.tf ファイルで、リージョンはクラスタ リソースの location フィールドに設定されています。

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

    versions:
    - version: 1.16.3-gke.45
    - version: 1.16.2-gke.28
    - version: 1.16.1-gke.45
    - version: 1.16.0-gke.669
    - version: 1.15.6-gke.25
    - version: 1.15.5-gke.41
    
    An Anthos version must be made available on the admin cluster ahead of the user
    cluster creation or upgrade. Versions annotated with isInstalled=true are
    installed on the admin cluster for the purpose of user cluster creation or
    upgrade whereas other version are released and will be available for upgrade
    once dependencies are resolved.
    
    To install the version in the admin cluster, run:
    $ gcloud container vmware admin-clusters update my-admin-cluster --required-platform-version=VERSION
    
  4. 新しいバージョンのコンポーネントをダウンロードし、管理クラスタにデプロイします。

    gcloud vmware admin-clusters update ADMIN_CLUSTER_NAME \
      --project=PROJECT_ID \
      --location=REGION \
      --required-platform-version=VERSION
    

    このコマンドは、--required-platform-version で指定したバージョンのコンポーネントを管理クラスタにダウンロードし、そのコンポーネントをデプロイします。これらのコンポーネントにより、管理クラスタはそのバージョンのユーザー クラスタを管理できます。

  5. ユーザー クラスタの作成に使用した main.tf ファイルで、クラスタ リソースの on_prem_version を新しいバージョンに変更します。

  6. Ubuntu ノードプールと COS ノードプールのみ: ユーザー クラスタのコントロール プレーンのみをアップグレードし、すべてのノードプールを現在のバージョンのままにする場合は、クラスタ リソースに次を追加します。

    upgrade_policy {
      control_plane_only = true
    }
    
  7. Terraform プランを初期化して作成します。

    terraform init
    

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

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

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

    terraform apply
    

ノードプールをアップグレードする

ユーザー クラスタのコントロール プレーンのみをアップグレードする場合は、ユーザー クラスタのコントロール プレーンをアップグレードした後、次の手順に沿って追加のノードプールをアップグレードします。

  1. アップグレードする各ノードプールのリソースの main.tf に、次の内容を追加します。

    on_prem_version = "VERSION"
    

    次に例を示します。

    resource "google_gkeonprem_vmware_node_pool" "nodepool-basic" {
    name = "my-nodepool"
    location = "us-west1"
    vmware_cluster = google_gkeonprem_vmware_cluster.default-basic.name
    config {
      replicas = 3
      image_type = "ubuntu_containerd"
      enable_load_balancer = true
    }
    on_prem_version = "1.16.0-gke.0"
    }
    
  2. Terraform プランを初期化して作成します。

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

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

    terraform apply
    

管理クラスタのアップグレード

始める前に、次のことを行います。

  • 証明書が最新かどうかを確認し、必要に応じて更新します。

  • バージョン 1.13 以降にアップグレードする場合は、まず管理クラスタの構成ファイルの gkeConnect セクションに入力して管理クラスタを登録する必要があります。構成ファイルを変更して クラスタの更新 コマンドを実行します。

新しい管理ワークステーションで、このセクションの手順を行います。gkectl とクラスタがアップグレードに合ったバージョンになっており、適切なバンドルがダウンロードされていることを確認します。

  1. 管理クラスタ構成ファイルbundlepath フィールドが、アップグレード先のバンドルのパスと一致していることを確認します。

    管理クラスタ構成ファイルのフィールドで他の変更を行っている場合、その変更はアップグレード時に無視されます。そうした変更を有効にするには、まずクラスタをアップグレードした後、構成ファイルを変更して更新コマンドを実行することで、他の変更をクラスタに施す必要があります。

  2. 次のコマンドを実行します。

    gkectl upgrade admin \
        --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
        --config ADMIN_CLUSTER_CONFIG_FILE \
        FLAGS
    

    以下を置き換えます。

    • ADMIN_CLUSTER_KUBECONFIG: 管理クラスタの kubeconfig ファイル。

    • ADMIN_CLUSTER_CONFIG_FILE: 新しい管理ワークステーション上の GKE on VMware 管理クラスタの構成ファイル。

    • FLAGS: オプションの一連のフラグ。たとえば、vSphere インフラストラクチャのチェックをスキップする --skip-validation-infra フラグを指定できます。

バージョン 1.14.0 以降にアップグレードすると、管理クラスタ用に新しい kubeconfig ファイルが生成され、既存のファイルは上書きされます。ファイル内のクラスタの詳細を表示するには、次のコマンドを実行します。

  kubectl config view --kubeconfig ADMIN_CLUSTER_KUBECONFIG 

フルバンドルをダウンロードした後、gkectl prepare コマンドと gkectl upgrade admin コマンドが正常に実行されたら、管理ワークステーションのディスク スペースを節約するために、フルバンドルを削除する必要があります。次のコマンドを使用します。

rm /var/lib/gke/bundles/gke-onprem-vsphere-${TARGET_VERSION}-full.tgz

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

管理クラスタのアップグレードが中断または失敗した場合で、管理クラスタのチェックポイントに、中断前の状態を復元するために必要な状態が含まれている場合は、アップグレードを再開できます。

警告: アップグレードの失敗後は、gkectl repair admin-master で管理マスターを修復しないでください。これを行うと、管理クラスタが不正な状態になります。

手順は次のとおりです。

  1. 最初のアップグレードの実施を始める前に、管理コントロール プレーンが正常かどうかを確認します。クラスタの問題を診断するをご覧ください。そのトピックで説明されているように、管理クラスタに対して gkectl diagnose cluster コマンドを実行します。

  2. 最初のアップグレード試行の前に、管理コントロール プレーンが正常でない場合は、gkectl repair admin-master コマンドで管理コントロール プレーンを修復します。

  3. アップグレードが中断または失敗した後にアップグレード コマンドを再実行すると、以前のアップグレード試行と同じバンドルとターゲット バージョンが使用されます。

アップグレード コマンドを再実行すると、チェックポイントから管理クラスタの状態が再作成され、アップグレード全体が再実行されます。1.12.0 以降、管理コントロール プレーンが正常でない場合、アップグレード プロセスは、アップグレードに進む前にソース バージョンで管理クラスタを復元せず、直接ターゲット バージョンにアップグレードされます。

管理クラスタのチェックポイントが使用可能な場合、アップグレードは失敗した時点か、終了した時点から再開されます。チェックポイントが使用できない場合は、アップグレードが管理コントロール プレーンへの依存にフォールバックするため、アップグレードを進めるには管理コントロール プレーンが正常である必要があります。アップグレードが成功すると、チェックポイントは再生成されます。

管理クラスタのアップグレード中に gkectl が予期せず終了した場合、その種類のクラスタはクリーンアップされません。アップグレード コマンドを再実行してアップグレードを再開する前に、その種類のクラスタを削除します。

docker stop gkectl-control-plane && docker rm gkectl-control-plane

種類クラスタを削除したら、アップグレード コマンドを再度実行します。

アップグレード後に管理ワークステーションをロールバックする

管理ワークステーションは、アップグレード前に使用したバージョンにロールバックできます。

アップグレード中、gkeadm はアップグレード前のバージョンを出力情報ファイルに記録します。ロールバック中、gkeadm はリストされたバージョンを使用して古いファイルをダウンロードします。

管理ワークステーションを以前のバージョンにロールバックするには:

gkeadm rollback admin-workstation --config=AW_CONFIG_FILE

管理ワークステーション構成ファイルがデフォルトの admin-ws-config.yaml の場合は、--config=AW_CONFIG_FILE を省略できます。それ以外の場合は、AW_CONFIG_FILE を管理ワークステーションの構成ファイルのパスに置き換えます。

rollback コマンドは、次の手順を実行します。

  1. gkeadm のロールバック バージョンをダウンロードします。
  2. 現在の管理ワークステーションのホーム ディレクトリをバックアップします。
  3. gkeadm のロールバック バージョンを使用して、新しい管理ワークステーションを作成します。
  4. 元の管理ワークステーションを削除します。

アップグレード用に別バージョンのバンドルをインストールする

ワークステーションをアップグレードすると、クラスタのアップグレード用に、対応するバージョンのバンドルがインストールされます。別のバージョンが必要な場合は、次の手順に沿って TARGET_VERSION のバンドルをインストールします。これはアップグレード後のバージョンです。

  1. 現在の gkectl とクラスタのバージョンを確認するには、次のコマンドを実行します。詳細は、フラグ --details/-d を使用して確認してください。

    gkectl version --kubeconfig ADMIN_CLUSTER_KUBECONFIG --details
    

    出力には、クラスタのバージョンに関する情報が表示されます。

  2. 取得した出力に基づいて、次の問題を確認し、必要に応じて修正します。

    • 現在の管理クラスタのバージョンが TARGET_VERSION よりマイナー バージョンで 1 バージョン超低い場合は、すべてのクラスタを TARGET_VERSION より 1 マイナー バージョン低いバージョンにアップグレードします。

    • gkectl バージョンが 1.11 未満で、1.12.x にアップグレードする場合は、アップグレードを複数回行う必要があります。1.11.x になるまではマイナー バージョンを 1 つずつアップグレードしてから、このトピックの手順に進んでください。

    • gkectl バージョンが TARGET_VERSION より新しいバージョンの場合は、TARGET_VERSION管理ワークステーションをアップグレードします。

  3. gkectl とクラスタ バージョンがアップグレードに適していると判断した場合は、バンドルをダウンロードします。

    バンドルの tarball が管理ワークステーションに存在するかどうかを確認します。

    stat /var/lib/gke/bundles/gke-onprem-vsphere-TARGET_VERSION.tgz

    バンドルが管理ワークステーションにない場合は、ダウンロードします。

    gsutil cp gs://gke-on-prem-release/gke-onprem-bundle/TARGET_VERSION/gke-onprem-vsphere-TARGET_VERSION.tgz /var/lib/gke/bundles/
    

  4. バンドルをインストールします。

    gkectl prepare --bundle-path /var/lib/gke/bundles/gke-onprem-vsphere-TARGET_VERSION.tgz --kubeconfig ADMIN_CLUSTER_KUBECONFIG
    

    ADMIN_CLUSTER_KUBECONFIG は、kubeconfig ファイルのパスに置き換えます。ファイルが現在のディレクトリにあり、名前が kubeconfig の場合、このフラグを省略できます。

  5. 使用可能なクラスタ バージョンを一覧表示し、使用可能なユーザー クラスタ バージョンにターゲット バージョンが含まれていることを確認します。

    gkectl version --kubeconfig ADMIN_CLUSTER_KUBECONFIG --details

これで、ターゲット バージョンでユーザー クラスタを作成することや、ユーザー クラスタをターゲット バージョンにアップグレードすることが可能になります。

アップグレード プロセスのトラブルシューティング

推奨するアップグレード プロセスに従って問題が発生した場合は、次の手順で解決することをおすすめします。以下の推奨事項は、バージョン 1.11.x のセットアップをすでに開始しており、推奨のアップグレード プロセスを進めることを前提としています。

クラスタの作成とアップグレードに関するトラブルシューティングをご覧ください。

ユーザー クラスタのアップグレードに関する問題のトラブルシューティング

ユーザー クラスタのアップグレード時にアップグレード バージョンに問題があるとします。今後のパッチリリースで問題が解決することを Google サポートに確認します。次のように進めることができます。

  1. 本番環境では、引き続き現在のバージョンを使用します。
  2. リリース時には、非本番環境クラスタでパッチリリースをテストします。
  3. 問題ないと判断できる場合は、すべての本番環境ユーザー クラスタをパッチリリース バージョンにアップグレードします。
  4. 管理クラスタをパッチリリース バージョンにアップグレードします。

管理クラスタのアップグレードに関する問題のトラブルシューティング

管理クラスタのアップグレード中に問題が発生した場合は、Google サポートに連絡して管理クラスタの問題を解決する必要があります。

新しいアップグレード フローを使用すれば、管理クラスタのアップグレードでブロックされることなく、ユーザー クラスタの新機能を利用できます。これにより、必要に応じて管理クラスタのアップグレード頻度を減らすことができます。アップグレード プロセスは次のようになります。

  1. 本番環境のユーザー クラスタを 1.12.x にアップグレードします。
  2. 管理クラスタは以前のバージョンのままにして、セキュリティ パッチを引き続き受信します。
  3. テスト環境で管理クラスタの 1.11.x から 1.12.x へのアップグレードをテストし、問題があれば報告します。
  4. 1.12.x のパッチリリースで問題が解決した場合は、必要に応じて本番環境管理クラスタをこのパッチリリースにアップグレードすることも可能です。

最近のバージョンに関する既知の問題

バージョン 1.7 以降からアップグレードすると、以下の既知の問題がアップグレードに影響を及ぼすことがあります。

既知の問題もご覧ください。

データディスクの残り容量が僅かになると、管理ワークステーションのアップグレードが失敗することがある

gkectl upgrade admin-workstation コマンドを使用して管理ワークステーションをアップグレード場合、データディスクの残り容量が僅かになるとアップグレードが失敗することがあります。これは、新しい管理ワークステーションへのアップグレード中に、現在の管理ワークステーションのバックアップがローカルで試行されるためです。データディスクの空き容量を確保できない場合は、--backup-to-local=false フラグが追加された gkectl upgrade admin-workstation コマンドを使用して、現在の管理ワークステーションのバックアップがローカルで作成されないようにします。

PodDisruptionBudgets を使用するワークロードが中断する

現時点では、クラスタをアップグレードすると、PodDisruptionBudgets(PDB)を使用するワークロードで中断やダウンタイムが発生することがあります。

ノードがアップグレード プロセスを完了できない

追加の中断を許可できない PodDisruptionBudget オブジェクトが構成されている場合、ノードのアップグレードを繰り返し試行しても、コントロール プレーン バージョンへのアップグレードが失敗する可能性があります。このエラーを回避するには、Deployment または HorizontalPodAutoscaler をスケールアップして、PodDisruptionBudget 構成を維持しながらノードをドレインすることをおすすめします。

中断を許可しないすべての PodDisruptionBudget オブジェクトを表示するには、次を行います。

kubectl get poddisruptionbudget --all-namespaces -o jsonpath='{range .items[?(@.status.disruptionsAllowed==0)]}{.metadata.name}/{.metadata.namespace}{"\n"}{end}'

付録

バージョン 1.1.0-gke.6 で有効になっている VMware DRS ルールについて

バージョン 1.1.0-gke.6 以降、GKE on VMware はユーザー クラスタのノードに対して VMware Distributed Resource Scheduler(DRS)の反アフィニティ ルールを自動的に作成し、データセンター内の少なくとも 3 つの物理ホストにそれらを分散させます。バージョン 1.1.0-gke.6 以降、この機能は新しいクラスタと既存のクラスタで自動的に有効になります。

アップグレードを行う前に、vSphere 環境が次の条件を満たしていることを確認してください。

  • VMware DRS が有効になっていること。VMware DRS には、vSphere Enterprise Plus ライセンス エディションが必要です。DRS を有効にする方法については、クラスタ内の VMware DRS の有効化をご覧ください。

  • 認証情報の構成ファイルで指定される vSphere ユーザー名には、Host.Inventory.EditCluster 権限があります。

  • 利用可能な物理ホストが少なくとも 3 つあること。

vSphere 環境が上記の条件を満たさない場合でも、ユーザー クラスタをアップグレードできます。ただし、1.3.x から 1.4.x にアップグレードする場合は、反アフィニティ グループを無効にする必要があります。詳細については、GKE on VMware リリースノートの既知の問題をご覧ください。

アップグレード中のダウンタイムについて

リソース 説明
管理クラスタ

管理クラスタが停止しても、ユーザー クラスタのコントロール プレーンとワークロードは、ダウンタイムの原因となった障害の影響を受けない限り引き続き実行されます。

ユーザー クラスタのコントロール プレーン

通常、ユーザー クラスタ コントロール プレーンには目立ったダウンタイムはありません。ただし、Kubernetes API サーバーへの長時間実行の接続が切断され、再確立する必要がある場合があります。この場合、API 呼び出し元は、接続が確立するまで再試行する必要があります。最悪のケースでは、アップグレード中に最大 1 分間のダウンタイムが発生することがあります。

ユーザー クラスタノード

アップグレードでユーザー クラスタ ノードの変更が必要な場合、GKE on VMware はノードをローリング方式で再作成し、これらのノードで実行されている Pod を再スケジュールします。ワークロードへの影響を防ぐには、適切な PodDisruptionBudgetsアンチ アフィニティ ルールを構成します。

情報ファイルがない場合は再作成する

管理ワークステーションの出力情報ファイルがない場合にアップグレードを続行するには、このファイルを再作成する必要があります。このファイルは、最初にワークステーションを作成したときに作成され、その後アップグレードすると最新の情報で更新されていました。

出力情報ファイルは、次のような形式です。

Admin workstation version: GKEADM_VERSION
Created using gkeadm version: GKEADM_VERSION
VM name: ADMIN_WS_NAME
IP: ADMIN_WS_IP
SSH key used: FULL_PATH_TO_ADMIN_WS_SSH_KEY
To access your admin workstation:
ssh -i FULL-PATH-TO-ADMIN-WS-SSH-KEY ubuntu@ADMIN-WS-IP

出力情報ファイルの例を次に示します。

Admin workstation version: v1.10.3-gke.49
Created using gkeadm version: v1.10.3-gke.49
VM name: admin-ws-janedoe
IP: 172.16.91.21
SSH key used: /usr/local/google/home/janedoe/.ssh/gke-admin-workstation
Upgraded from (rollback version): v1.10.0-gke.194
To access your admin workstation:
ssh -i /usr/local/google/home/janedoe/.ssh/gke-admin-workstation ubuntu@172.16.91.21

パラメータを適切に置き換えて、エディタでファイルを作成します。gkeadm が実行されるディレクトリに、VM 名と同じファイル名でファイルを保存します。たとえば、VM 名が admin-ws-janedoe の場合は、ファイルを admin-ws-janedoe として保存します。

次のステップ