VMware 用 Google Distributed Cloud（ソフトウェアのみ）の管理ワークステーション、ユーザー クラスタ、管理クラスタをアップグレードすると、サポートされている Kubernetes リリース、セキュリティ パッチ、プラットフォーム機能を採用できます。このドキュメントでは、ユーザー クラスタのコントロール プレーンとノードプールを一緒にアップグレードする手順について説明します。個別にアップグレードするには、ノードプールをアップグレードするをご覧ください。
始める前に、ツールの選択とアップグレードの順序についてはアップグレードの概要、リリース固有のバージョンスキューと OS の要件についてはアップグレード バージョンのルール、アップグレード前のチェックリストについてはアップグレードのベスト プラクティスをご覧ください。
始める前に
アップグレードを開始する前に、管理クラスタとユーザー クラスタの最新のバックアップがあることを確認してください。詳細については、ユーザー クラスタと管理クラスタをバックアップするをご覧ください。
アップグレードする前に、クラスタを診断します。
gkectl diagnose clusterを実行して、管理クラスタが正常であることを確認し、アップグレードを開始する前に問題を解決します。gkectlとクラスタがアップグレードに合ったバージョンになっており、適切なバンドルがダウンロードされていることを確認します。管理クラスタとユーザー クラスタの間のバージョン スキューは、Google Distributed Cloud のバージョンによって異なります。管理クラスタをアップグレードできることを確認するには、お使いのバージョンのバージョン ルールをご覧ください。管理クラスタ構成ファイルの
bundlepathフィールドが、アップグレード先のバンドルのパスと一致していることを確認します。管理クラスタ構成ファイルのフィールドで他の変更を行っている場合、その変更はアップグレード時に無視されます。そうした変更を有効にするには、まずクラスタをアップグレードした後、構成ファイルを変更して更新コマンドを実行することで、他の変更をクラスタに施す必要があります。
ファイアウォール ルールを確認する
バージョン 1.29 以降では、サーバーサイドのプリフライト チェックはデフォルトで有効になっています。サーバーサイドのプリフライト チェックには、追加のファイアウォール ルールが必要です。管理クラスタのファイアウォール ルールで、[プリフライト チェック] を検索し、必要なファイアウォール ルールがすべて構成されていることを確認します。
サーバーサイドのプリフライト チェックでは、gkectl を使用してユーザー クラスタをアップグレードすると、プリフライト チェックは、管理ワークステーションでローカルではなく、管理クラスタで実行されます。 Google Cloud コンソール、Google Cloud CLI、または Terraform を使用してクラスタをアップグレードすると、管理クラスタでサーバーサイド プリフライト チェックも実行されます。
管理クラスタをアップグレードすると、Google Distributed Cloud は Docker 内の Kubernetes（kind）クラスタをデプロイして、管理クラスタのアップグレードに必要な Kubernetes コントローラを一時的にホストします。この一時的なクラスタは、ブートストラップ クラスタと呼ばれます。管理クラスタをアップグレードすると、ブートストラップ クラスタでサーバーサイドのプリフライト チェックが実行されます。
stackdriver を有効にする
gkectl を使用してユーザー クラスタを作成した場合は、アップグレードする前に、ユーザー クラスタの構成ファイルの stackdriver セクションに入力されていることを確認してください。これにより、stackdriver（ロギングとモニタリングに必要）が有効になります。stackdriver が有効になっていない場合は、ユーザー クラスタの構成ファイルの stackdriver セクションに入力し、アップグレードする前にクラスタを更新します。
Terraform、 Google Cloud コンソール、または gcloud CLI を使用してクラスタを作成した場合、stackdriver は自動的に有効になります。
Dataplane V2 を有効にする
バージョン 1.31 以降では、すべてのユーザー クラスタで Dataplane V2 を有効にする必要があります。ユーザー クラスタを 1.31 にアップグレードする前に、次の手順を実施します。NetworkPolicy 仕様の一時的な削除について懸念がある場合は、Google サポートにお問い合わせください。
ユーザー クラスタの構成ファイルで、enableDataplaneV2 を true に設定します。
クラスタで NetworkPolicy を使用している場合は、次のようにクラスタからその仕様を一時的に削除します。
クラスタにシステム以外の
NetworkPolicyが適用されているかどうかを確認します。kubectl --kubeconfig USER_CLUSTER_KUBECONFIG \ get networkpolicy -A -o wide \ --field-selector metadata.namespace!=kube-systemUSER_CLUSTER_KUBECONFIGは、ユーザー クラスタの kubeconfig ファイルのパスに置き換えます。デフォルトの
kube-systemポリシーのみが存在する場合、コマンドはNo resources foundを返します。前のコマンドで
NetworkPolicyオブジェクトが一覧表示された場合は、各NetworkPolicy仕様をファイルに保存して、クラスタのアップグレード後に仕様を再適用できるようにします。kubectl --kubeconfig USER_CLUSTER_KUBECONFIG get networkpolicy NETWORK_POLICY_NAME -n NETWORK_POLICY_NAMESPACE -o yaml > NETWORK_POLICY_NAME.yaml次のように置き換えます。
NETWORK_POLICY_NAME: 保存するNetworkPolicyの名前。NETWORK_POLICY_NAMESPACE:NetworkPolicyの名前空間。
次のコマンドを使用して
NetworkPolicyを削除します。kubectl --kubeconfig USER_CLUSTER_KUBECONFIG delete networkpolicy NETWORK_POLICY_NAME -n NETWORK_POLICY_NAMESPACEアップグレードを続行します。
アップグレードの完了後、システム以外の
NetworkPolicy仕様を削除した場合は、次のコマンドで再適用します。kubectl --kubeconfig USER_CLUSTER_KUBECONFIG apply -f NETWORK_POLICY_NAME.yaml
Google API と IAM の要件
クラスタをバージョン 1.28 以降にアップグレードするには、kubernetesmetadata.googleapis.com を有効にして、logging-monitoring サービス アカウントに kubernetesmetadata.publisher IAM ロールを付与する必要があります。これらの変更は、Cloud Monitoring を使用するために必要です。
kubernetesmetadata.googleapis.comを有効にします。gcloud services enable --project PROJECT_ID \ kubernetesmetadata.googleapis.comPROJECT_IDは、クラスタがメンバーであるフリート ホスト プロジェクトの ID に置き換えます。これは、クラスタの作成時に指定したプロジェクトです。gkectlを使用してクラスタを作成した場合、これはクラスタ構成ファイルのgkeConnect.projectIDフィールドのプロジェクト ID です。Google API や他のアドレスからのトラフィックがプロキシ サーバーを通過できるよう組織が許可リストを設定している場合は、
kubernetesmetadata.googleapis.comを許可リストに追加します。ロギング モニタリング サービス アカウントに
kubernetesmetadata.publisherロールを付与します。gcloud projects add-iam-policy-binding PROJECT_ID \ --member "serviceAccount:SERVICE_ACCOUNT_EMAIL" \ --role "roles/kubernetesmetadata.publisher"SERVICE_ACCOUNT_EMAILは、logging-monitoring サービス アカウントのメールアドレスに置き換えます。
アップグレードで以前の特徴量がブロックされる
クラスタをバージョン 1.32 にアップグレードする際、次のレガシー機能はブロックされます。
- Dataplane V1（Calico）
- 統合型 F5 BIG-IP ロードバランサの構成
- 非 HA 管理クラスタ
- kubeception ユーザー クラスタ
- Seesaw ロードバランサ
バージョン 1.32 にアップグレードする前に、クラスタを推奨機能に移行する必要があります。
ユーザー クラスタをアップグレードするための 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 ロールの説明をご覧ください。
高度なクラスタの制限事項
高度なクラスタを有効にしている場合、次の制限事項に注意してください。
クラスタをバージョン 1.32 から 1.33 にアップグレードする場合は、
gkectlを使用する必要があります。GKE On-Prem API クライアント（コンソール、gcloud CLI、Terraform）は、この特定のアップグレード パスではサポートされていませんが、バージョン 1.33 以降のアップグレードではサポートされています。バージョン 1.31 プレビューの高度なクラスタの場合、または高度なクラスタ以外の管理クラスタを高度な管理クラスタに変換する場合は、同期アップグレードを実行する必要があります。バージョン 1.32 以降では、既存の高度なクラスタに対して
gkectl upgrade adminコマンドとgkectl upgrade clusterコマンドで--asyncフラグを使用できます。
アップグレードの前または後に構成を変更する
クラスタの構成を変更する必要がある場合は、アップグレードの前または後にクラスタの更新を行います。アップグレードに対して変更するクラスタ構成のは、バージョンのみです。クラスタのバージョンとタイプによっては、他の構成変更は通知なく無視されるか、アップグレードが失敗する原因になります。詳細については、サポートされていない変更を削除してアップグレードのブロックを解除するをご覧ください。
クラスタ アップグレードに使用可能なバージョンを確認する
次のコマンドを実行して、アップグレードで利用可能なバージョンを確認します。
gkectl version --kubeconfig ADMIN_CLUSTER_KUBECONFIG
ADMIN_CLUSTER_KUBECONFIG は、管理クラスタの kubeconfig ファイルのパスに置き換えます。
出力に、現在のバージョンとアップグレードで利用可能なバージョンが表示されます。
アップグレードにコンソール、gcloud CLI、または Terraform を使用する場合、すべての Google Cloud リージョンの GKE On-Prem API でバージョンが使用可能になるまでリリースから約 7～14 日かかります。コンソールには、ユーザー クラスタのアップグレードで利用可能なバージョンのみが一覧表示されます。gcloud CLI または Terraform を使用してユーザー クラスタをアップグレードする手順には、gcloud container vmware clusters query-version-config を実行してアップグレードに使用可能なバージョンを取得する手順が含まれています。
管理ワークステーションをアップグレードする
管理ワークステーションのアップグレード方法は、作成方法（gkeadm またはユーザー管理）によって異なります。
gkeadm
必要なファイルを探す
管理ワークステーションを作成する前に、gkeadm create config によって生成された管理ワークステーションの構成ファイルに入力しました。このファイルのデフォルト名は admin-ws-config.yaml です。
また、ワークステーションにも情報ファイルがあります。このファイルのデフォルト名は、管理ワークステーションの名前と同じです。
管理ワークステーションの構成ファイルと情報ファイルを探します。アップグレード手順を実行するには、それらが必要です。これらのファイルが現在のディレクトリにあり、デフォルトの名前が使われている場合は、アップグレード コマンドを実行するときに名前を指定する必要はありません。これらのファイルが別のディレクトリにある場合や、ファイル名を変更した場合は、--config フラグと --info-file フラグを使用して指定します。
出力情報ファイルがない場合は、再作成できます。情報ファイルがない場合は再作成するをご覧ください。
アップグレード
管理ワークステーションをアップグレードします。
管理ワークステーションの構成ファイルで
adminWorkstation.diskGBフィールドを調べ、指定されているサイズが 100 以上であることを確認します。次に例を示します。adminWorkstation: diskGB: 1001.28 以降にアップグレードする場合は 100 GB が必要です。管理ワークステーションに十分なディスク容量がない場合、クラスタのアップグレードは失敗します。
踏み台サーバーから
gkeadmをダウンロードします。gkeadm upgrade gkeadm --target-version TARGET_VERSION
TARGET_VERSIONは、アップグレードするバージョンに置き換えます。完全なバージョン番号をX.Y.Z-gke.Nの形式で指定する必要があります。 Google Distributed Cloud のバージョンのリストについては、バージョニングをご覧ください。管理ワークステーションをアップグレードする
gkeadm upgrade admin-workstation --config AW_CONFIG_FILE \ --info-file INFO_FILE
次のように置き換えます。
AW_CONFIG_FILE: 管理ワークステーションの構成ファイルのパス。ファイルが現在のディレクトリにあり、名前がadmin-ws-config.yamlの場合、このフラグを省略できます。INFO_FILE: 情報ファイルのパスを指定します。ファイルが現在のディレクトリにある場合は、このフラグを省略できます。このファイルのデフォルト名は、管理ワークステーションの名前と同じです。
ユーザー管理
管理ワークステーションで、新しいバージョンの gkectl をインストールするディレクトリに移動します。
gkectlをダウンロードします。gcloud storage cp gs://gke-on-prem-release/gkectl/TARGET_VERSION/gkectl ./ chmod +x gkectl
TARGET_VERSIONは、アップグレードするバージョンに置き換えます。完全なバージョン番号をX.Y.Z-gke.Nの形式で指定する必要があります。Google Distributed Cloud のバージョンのリストについては、バージョニングをご覧ください。Google Distributed Cloud バンドルをダウンロードします。バージョンが、
gkectlのダウンロードに使用したバージョンと一致していることを確認します。gcloud storage cp gs://gke-on-prem-release/gke-onprem-bundle/TARGET_VERSION/gke-onprem-vsphere-TARGET_VERSION.tgz ./
管理クラスタをアップグレードする
管理クラスタをアップグレードする手順は、アップグレード先のマイナー バージョン（ターゲット バージョン）によって若干異なります。
1.31 以降
ターゲット バージョンが 1.31 以降の場合は、ユーザー クラスタを次のマイナー バージョンにアップグレードする前に、管理クラスタをアップグレードする必要があります。1.31 以降では、パッチ バージョンを含む管理クラスタのバージョンがユーザー クラスタのバージョン以上である必要があります。たとえば、管理クラスタのバージョンが 1.31.1 の場合、ユーザー クラスタは最大でバージョン 1.31.1 までアップグレードできます。
管理ワークステーションで次のコマンドを実行して、OS イメージを vSphere にインポートします。
gkectl prepare \
--bundle-path /var/lib/gke/bundles/gke-onprem-vsphere-TARGET_VERSION.tgz \
--kubeconfig ADMIN_CLUSTER_KUBECONFIG
ADMIN_CLUSTER_KUBECONFIG は、管理クラスタの kubeconfig ファイルのパスに置き換えます。
1.30 以前
ターゲット バージョンが 1.30 以前の場合は、管理クラスタをアップグレードする前に、すべてのユーザー クラスタをアップグレードする必要があります。管理クラスタのマイナー バージョンは、ユーザー クラスタのマイナー バージョン以下にする必要があります。パッチ バージョンは関係ありません。たとえば、ユーザー クラスタのバージョンが 1.30.1 の場合、管理クラスタを 1.30.3 などのよりグレードの高いパッチ バージョンにアップグレードできます。
アップグレードを実行する
gkectl
新しい管理ワークステーションで、このセクションの手順を行います。gkectl upgrade admin コマンドには次の 2 つのバリエーションがあります。
非同期:
非同期のバリエーションでは、コマンドはアップグレードを開始して最後まで進みます。アップグレードの期間全体を通して、コマンドの出力を監視する必要はありません。そうする代わりに、gkectl list adminとgkectl describe adminを実行して、アップグレードの進行状況を定期的に確認できます。非同期のバリエーションを使用するには、コマンドに--asyncフラグを追加します。非同期アップグレードの要件:
- バージョン 1.29 以降の HA 管理クラスタでのみサポートされます。
- すべてのユーザー クラスタで Controlplane V2 を有効にする必要があります。
- バージョン 1.31: 高度なクラスタではサポートされていません。
- バージョン 1.32 以降: 高度なクラスタで使用できます。
同期:
同期のバリエーションでは、アップグレードが進むと、gkectl upgrade adminコマンド出力が管理ワークステーションに表示されます。
非同期アップグレード
管理ワークステーションで、アップグレードする前にクラスタを診断します。
gkectl diagnose cluster \ --kubeconfig ADMIN_CLUSTER_KUBECONFIG
コマンドでエラーまたは警告が報告された場合は、クラスタの問題を診断するを参照して、問題を解決してから続行してください。
非同期アップグレードを開始します。
gkectl upgrade admin \ --kubeconfig ADMIN_CLUSTER_KUBECONFIG \ --config ADMIN_CLUSTER_CONFIG_FILE \ --async
次のように置き換えます。
ADMIN_CLUSTER_KUBECONFIG: 管理クラスタの kubeconfig ファイルへのパス。ADMIN_CLUSTER_CONFIG_FILE: 管理クラスタの構成ファイルへのパス。
上記のコマンドは完了し、アップグレードの進行中も管理ワークステーションを引き続き使用できます。
アップグレードのステータスを確認するには:
gkectl list admin --kubeconfig ADMIN_CLUSTER_KUBECONFIG
出力には、クラスタ
STATEの値が表示されます。クラスタがまだアップグレード中である場合、STATEの値はUPGRADINGです。例:NAME STATE AGE VERSION gke-admin-test UPGRADING 9h 1.36.100-gke.144
STATEの想定される値は、RUNNING、UPGRADING、RECONCILING、ERROR、UNKNOWNです。アップグレードの進行状況とクラスタ イベントの詳細を確認するには:
gkectl describe admin --kubeconfig ADMIN_CLUSTER_KUBECONFIG
出力には、指定した管理クラスタの OnPremAdminCluster カスタム リソースが表示されます。これには、クラスタのステータスと条件が含まれます。
クリックして出力例を表示
Status: Cluster State: RUNNING Conditions: Last Transition Time: 2026-08-10T20:22:58Z Message: Operator NodePool is ready Observed Generation: 2 Reason: OperatorNodePoolReady Status: True Type: ControlPlaneReady Last Transition Time: 2026-08-10T20:22:59Z Message: Cluster is running Observed Generation: 2 Reason: ClusterRunning Status: True Type: Ready Last Transition Time: 2026-08-10T20:23:00Z Message: Observed Generation: 2 Reason: Reconciling Status: False Type: OperatorClusterKubeProxyCleanedUp Last Transition Time: 2026-08-10T20:22:58Z Message: Observed Generation: 2 Reason: PreflightCheckPassed Status: True Type: OperatorClusterPreflightCheckSuccessful Last Transition Time: 2026-08-10T15:56:50Z Message: Observed Generation: 2 Reason: ProvisioningStarted Status: True Type: OperatorClusterProvisioningStarted Last Transition Time: 2026-08-10T15:56:50Z Message: Observed Generation: 2 Reason: RemoteTrackerSetupComplete Status: True Type: OperatorClusterRemoteTrackerSetupSuccessful Last Transition Time: 2026-08-10T15:56:50Z Message: Observed Generation: 2 Reason: Reconciling Status: False Type: OperatorClusterStalled Last Transition Time: 2026-08-10T15:56:50Z Message: Observed Generation: 2 Reason: NotPresent Status: False Type: OperatorClusterWaitingOnPendingClusterID Last Transition Time: 2026-08-10T20:22:59Z Message: Operator Cluster is ready Observed Generation: 2 Reason: OperatorClusterReady Status: True Type: OperatorClusterReady Last Transition Time: 2026-08-10T15:56:50Z Message: Component provisioner job is completed Observed Generation: 2 Reason: ComponentProvisionerJobCompleted Status: True Type: ComponentProvisionerSystemProfileInstalled Last Transition Time: 2026-08-10T15:58:20Z Message: Component provisioner job is completed Observed Generation: 2 Reason: ComponentProvisionerJobCompleted Status: True Type: ComponentProvisionerAdminProfileInstalled Gke On Prem Version: 1.36.0-gke.527 Last Gke On Prem Version: 1.35.300-gke.87 Management Conditions: Last Transition Time: 2026-08-10T15:58:20Z Message: Component provisioner job is completed Observed Generation: 2 Reason: ComponentProvisionerJobCompleted Status: True Type: ManagementProfilesReady Last Transition Time: 2026-08-10T15:56:29Z Message: Component provisioner job is completed Observed Generation: 2 Reason: ComponentProvisionerJobCompleted Status: True Type: ComponentProvisionerSystemManagementProfileInstalled Last Transition Time: 2026-08-10T15:58:20Z Message: Component provisioner job is completed Observed Generation: 2 Reason: ComponentProvisionerJobCompleted Status: True Type: ComponentProvisionerManagementProfileInstalled Operator Cluster Status: Control Plane Node Pool Status: Anthos Bare Metal Version: 1.36.0-gke.527 Anthos Bare Metal Versions: 1.36.0-gke.527: 3 Conditions: Last Transition Time: 2026-08-10T20:18:20Z Observed Generation: 11 Reason: PreflightCheckPassed Status: True Type: PreflightCheckSuccessful Last Transition Time: 2026-08-10T20:22:58Z Observed Generation: 11 Reason: NodepoolReady Status: True Type: Ready Last Transition Time: 2026-08-10T20:22:22Z Observed Generation: 11 Reason: ReconciliationCompleted Status: False Type: Reconciling Gke Versions: v1.36.0-gke.2800: 3 Last Reconciliation Time: 2026-08-10T20:25:07Z Maintenance Nodes: 0 Managed Fields: Label Keys: kubernetes.googleapis.com/cluster-name node.kubernetes.io/control-plane node.kubernetes.io/master Node Label Keys: vsphere://abcdef-1: onprem.gke.io/failure-domain-name vmware.cluster.gke.io/machine-name vsphere://abcdef-2: onprem.gke.io/failure-domain-name vmware.cluster.gke.io/machine-name vsphere://abcdef-3: onprem.gke.io/failure-domain-name vmware.cluster.gke.io/machine-name Taints: Effect: PreferNoSchedule Key: node-role.kubernetes.io/control-plane Ready Nodes: 3 Ready Timestamp: 2026-08-10T15:54:01Z Reconciling Nodes: 0 Stalled Nodes: 0 Unknown Nodes: 0 Data Plane Load Balancer Status: Conditions: Last Transition Time: 2026-08-10T15:39:16Z Observed Generation: 1 Reason: ReconciliationCompleted Status: False Type: Reconciling Node Pool Location: control-plane-nodepool External Manifests Conditions: Last Transition Time: 2026-08-10T15:56:32Z Observed Generation: 2 Reason: ReconciliationCompleted Status: False Type: Reconciling Gke Connect Conditions: Last Transition Time: 2026-08-10T20:13:39Z Observed Generation: 2 Reason: AnthosBareMetalVersion Status: True Type: 1.36.0-gke.527 Last Transition Time: 2026-08-10T20:13:39Z Observed Generation: 2 Reason: ReconciliationCompleted Status: False Type: Reconciling Gke Connect Dependent System Service Conditions: Last Transition Time: 2026-08-10T15:56:32Z Observed Generation: 2 Reason: ReconciliationCompleted Status: False Type: Reconciling Gke Hub Registration Status: Membership: Description: description Name: name Gke Versions: v1.36.0-gke.2800: 3 Kernel Version Conditions: Last Transition Time: 2026-08-10T15:39:23Z Reason: kernelVersionCheckPassed Status: True Type: kernelVersionCheckSuccessful System Service Conditions: Last Transition Time: 2026-08-10T20:12:26Z Observed Generation: 2 Reason: ReconciliationCompleted Status: False Type: Reconcilingアップグレードが完了すると、
gkectl list adminにRUNNINGのSTATEが表示されます。NAME STATE AGE VERSION gke-admin-test RUNNING 9h 1.36.100-gke.144また、アップグレードが完了すると、
gkectl describe adminによってStatusの下にLast GKE On Prem Versionフィールドが表示されます。例:Status: Cluster State: RUNNING Last GKE On Prem Version: 1.36.0-gke.1
非同期アップグレードのトラブルシューティング
非同期アップグレードの場合、タイムアウト時間はクラスタ内のノードの数に基づきます。アップグレードがタイムアウト時間よりも長くかかる場合、アップグレード オペレーションがタイムアウトしたことを示すイベントが発生し、クラスタの状態が UPGRADING から ERROR に変更されます。ここで、ERROR 状態は、アップグレードに予想より長い時間がかかっているものの、終了されていないことを意味します。コントローラは整合を続行し、オペレーションを再試行し続けます。アップグレードがブロックされた、または失敗した場合は、gkectl diagnose を実行して、一般的なクラスタの問題を確認できます。その結果に基づいて、手動で修正を行うか、Google Cloud サポートに連絡するかを決定できます。
同期アップグレード
管理ワークステーションで、アップグレードする前にクラスタを診断します。
gkectl diagnose cluster \ --kubeconfig ADMIN_CLUSTER_KUBECONFIG
コマンドでエラーまたは警告が報告された場合は、クラスタの問題を診断するを参照して、問題を解決してから続行してください。
管理クラスタをアップグレードします。
gkectl upgrade admin \ --kubeconfig ADMIN_CLUSTER_KUBECONFIG \ --config ADMIN_CLUSTER_CONFIG_FILE
次のように置き換えます。
ADMIN_CLUSTER_KUBECONFIG: 管理クラスタの kubeconfig ファイルのパス。ADMIN_CLUSTER_CONFIG_FILE: 管理クラスタの構成ファイルへのパス。
gkectl upgradeコマンドは、プリフライト チェックを実行します。プリフライト チェックが不合格の場合、コマンドはブロックされます。不備を修正するか、このコマンドでフラグ--skip-preflight-check-blockingを使用してブロックを解除する必要があります。バージョン 1.14.0 以降にアップグレードすると、管理クラスタ用に新しい kubeconfig ファイルが生成され、既存のファイルは上書きされます。ファイル内のクラスタの詳細を表示するには、次のコマンドを実行します。
kubectl config view --kubeconfig ADMIN_CLUSTER_KUBECONFIG
gcloud CLI
gcloud CLI を使用して管理クラスタをアップグレードします。
プラットフォーム バージョンをターゲット バージョンに更新します。
gcloud container vmware admin-clusters update ADMIN_CLUSTER_NAME \ --location=REGION \ --required-platform-version=VERSION \ --async次のように置き換えます。
ADMIN_CLUSTER_NAME: 管理クラスタの名前。REGION: 管理クラスタが管理されている Google Cloud リージョン。VERSION: アップグレード先のターゲット バージョン。
このコマンドはオペレーション ID を返します。
gcloud container vmware operations describeを使用して進行状況をモニタリングできます。プラットフォーム バージョンの更新が完了したら、管理クラスタのバージョンを更新します。
gcloud container vmware admin-clusters update ADMIN_CLUSTER_NAME \ --location=REGION \ --version=VERSION \ --asyncこの手順で、管理クラスタのターゲット バージョンへのアップグレードが完了します。
ユーザー クラスタをアップグレードする
ユーザー クラスタは、gkectl、コンソール、gcloud CLI、または Terraform を使用してアップグレードできます。使用するツールの選定については、クラスタをアップグレードするツールを選択するをご覧ください。
コンソール
ユーザー クラスタをアップグレードするには、管理クラスタにいくつかの変更を加える必要があります。コンソールでは、自動的に次の処理が行われます。
管理クラスタを GKE On-Prem API に登録します（まだ登録されていない場合）。
コンポーネントのバンドルをダウンロードして管理クラスタにデプロイします。コンポーネントのバージョンが、アップグレードに指定したバージョンと一致します。これらのコンポーネントを使用すると、管理クラスタがそのバージョンのユーザー クラスタを管理できるようになります。
ユーザー クラスタをアップグレードするには:
コンソールで、Google Kubernetes Engine クラスタの概要ページに移動します。
Google Cloud プロジェクトを選択し、アップグレードするクラスタを選択します。
[詳細] パネルで、[詳細] をクリックします。
[クラスタの基本] セクションで、 アップグレードをクリックします。
[ターゲット バージョンを選択] リストで、アップグレード後のバージョンを選択します。キュレーション リストには、最新のパッチリリースのみが含まれます。
[アップグレード] をクリックします。
クラスタがアップグレードされる前にプリフライト チェックが実行され、クラスタのステータスとノードの健全性が検証されます。プリフライト チェックに合格すると、ユーザー クラスタがアップグレードされます。アップグレードが完了するまでに約 30 分を要します。
アップグレードのステータスを表示するには、[クラスタの詳細] タブの [詳細を表示] をクリックします。
gcloud CLI
ユーザー クラスタをアップグレードするには、管理クラスタにいくつかの変更を加える必要があります。gcloud container vmware clusters upgrade コマンドは、自動的に次の処理を行います。
管理クラスタを GKE On-Prem API に登録します（まだ登録されていない場合）。
コンポーネントのバンドルをダウンロードして管理クラスタにデプロイします。コンポーネントのバージョンが、アップグレードに指定したバージョンと一致します。これらのコンポーネントを使用すると、管理クラスタがそのバージョンのユーザー クラスタを管理できるようになります。
ユーザー クラスタをアップグレードするには:
Google Cloud CLI のコンポーネントを更新します。
gcloud components updateアップグレード先として使用可能なバージョンのリストを取得します。
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コマンドで指定したバージョンに一致するコンポーネントのバンドルをダウンロードしてデプロイします。クラスタをアップグレードします。
gcloud container vmware clusters upgrade 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 です。 オペレーションのステータスを確認するには、別のターミナル ウィンドウで次のコマンドを実行します。gcloud container vmware operations describe OPERATION_ID \ --project=PROJECT_ID \ --location=REGION
gkectl
ユーザー クラスタのアップグレードの準備を行う
管理ワークステーションで、次の操作を行います。
最初のアップグレードの実施を始める前に、ユーザー クラスタが正常かどうかを確認します。クラスタの問題を診断するをご覧ください。ユーザー クラスタで
gkectl diagnose clusterを実行し、問題を解決します。この手順は、
TARGET_VERSIONが 1.30 以前の場合、またはユーザー クラスタを管理クラスタとは異なるバージョンにアップグレードする場合にのみ行います。gkectl prepareを実行して、OS イメージを vSphere にインポートします。gkectl prepare \ --bundle-path /var/lib/gke/bundles/gke-onprem-vsphere-TARGET_VERSION.tgz \ --kubeconfig ADMIN_CLUSTER_KUBECONFIG
クラスタに Windows ノードプールがある場合は、
gkectl prepare windowsを実行してノードプールのosImageフィールドを更新します。詳しい手順については、Windows ノードプールを含むユーザー クラスタをアップグレードするをご覧ください。ユーザー クラスタの構成ファイルで、
gkeOnPremVersionをアップグレードのターゲット バージョンに設定します。
プリフライト チェックを実行する
バージョン 1.29 以降にアップグレードする場合は、ユーザー クラスタをアップグレードする前にプリフライト チェックを実行できます。
gkectl upgrade cluster \
--kubeconfig ADMIN_CLUSTER_KUBECONFIG \
--config USER_CLUSTER_CONFIG \
--dry-run
USER_CLUSTER_CONFIG は、ユーザー クラスタ構成ファイルのパスに置き換えます。
--dry-run フラグを使用すると、gkectl upgrade cluster はプリフライト チェックを実行しますが、アップグレード プロセスは開始しません。以前のバージョンの Google Distributed Cloud では、プリフライト チェックが実行されますが、アップグレードとは別に実行することはできません。--dry-run フラグを追加すると、アップグレード前にプリフライト チェックでユーザー クラスタで見つかった問題を見つけて修正できます。
gkectl upgrade cluster を実行します
gkectl upgrade cluster コマンドには次の 2 つのバリエーションがあります。
非同期: （推奨）
非同期のバリエーションでは、コマンドはアップグレードを開始して最後まで進みます。アップグレードの期間全体を通して、コマンドの出力を監視する必要はありません。そうする代わりに、gkectl list clustersとgkectl describe clustersを実行して、アップグレードの進行状況を定期的に確認できます。非同期のバリエーションを使用するには、コマンドに--asyncフラグを追加します。- バージョン 1.31: 高度なクラスタでは使用できません。
- バージョン 1.32 以降: 高度なクラスタで使用できます。
同期:
同期のバリエーションでは、アップグレードが進むと、gkectl upgrade clusterコマンド出力が管理ワークステーションに表示されます。
非同期アップグレード
1.16 以降のバージョンにアップグレードする場合は、この手順をスキップしてください。
ユーザー クラスタに準備済みの認証情報と非公開レジストリを使用している場合は、ユーザー クラスタをアップグレードする前に、非公開レジストリの認証情報が準備されていることを確認してください。非公開レジストリの認証情報を準備する方法については、ユーザー クラスタの準備済みの認証情報を構成するをご覧ください。
クラスタを診断して、正常であることを確認します。
gkectl diagnose cluster \ --kubeconfig <var>ADMIN_CLUSTER_KUBECONFIG</var>コマンドでエラーまたは警告が報告された場合は、クラスタの問題を診断するを参照して、問題を解決してから続行してください。
管理ワークステーションで、非同期アップグレードを開始します。
gkectl upgrade cluster \ --kubeconfig ADMIN_CLUSTER_KUBECONFIG \ --config USER_CLUSTER_CONFIG \ --async
上記のコマンドは完了し、アップグレードの進行中も管理ワークステーションを引き続き使用できます。
アップグレードのステータスを確認するには:
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.36.0-gke.1
STATEの想定される値は、UPGRADING、DELETING、UPDATING、RUNNING、RECONCILING、ERROR、UNKNOWNです。アップグレードの進行状況とクラスタ イベントの詳細を確認するには:
gkectl describe clusters --kubeconfig ADMIN_CLUSTER_KUBECONFIG \ --cluster USER_CLUSTER_NAME -v 5
出力には、指定したユーザー クラスタの OnPremUserCluster カスタム リソースが表示されます。これには、クラスタのステータス、条件、イベントが含まれます。
クリックして出力例を表示
Status: Cluster State: RUNNING Conditions: Last Transition Time: 2026-08-10T21:29:07Z Message: Cluster is running Observed Generation: 2 Reason: ClusterRunning Status: True Type: Ready Last Transition Time: 2026-08-10T21:12:05Z Message: Operator NodePool is ready Observed Generation: 2 Reason: OperatorNodePoolReady Status: True Type: ControlPlaneReady Last Transition Time: 2026-08-10T16:25:08Z Message: Component provisioner job is completed Observed Generation: 2 Reason: ComponentProvisionerJobCompleted Status: True Type: ComponentProvisionerUserProfileInstalled Last Transition Time: 2026-08-10T21:29:07Z Message: Node pools are running Observed Generation: 2 Reason: NodePoolsRunning Status: True Type: NodePoolsReady Last Transition Time: 2026-08-10T21:29:56Z Message: Observed Generation: 2 Reason: Reconciling Status: False Type: OperatorClusterKubeProxyCleanedUp Last Transition Time: 2026-08-10T16:27:48Z Message: Observed Generation: 2 Reason: PreflightCheckPassed Status: True Type: OperatorClusterPreflightCheckSuccessful Last Transition Time: 2026-08-10T16:27:48Z Message: Observed Generation: 2 Reason: ProvisioningStarted Status: True Type: OperatorClusterProvisioningStarted Last Transition Time: 2026-08-10T16:27:48Z Message: Observed Generation: 2 Reason: RemoteTrackerSetupComplete Status: True Type: OperatorClusterRemoteTrackerSetupSuccessful Last Transition Time: 2026-08-10T16:27:48Z Message: Observed Generation: 2 Reason: Reconciling Status: False Type: OperatorClusterStalled Last Transition Time: 2026-08-10T16:27:48Z Message: Observed Generation: 2 Reason: NotPresent Status: False Type: OperatorClusterWaitingOnPendingClusterID Last Transition Time: 2026-08-10T18:23:16Z Message: Operator Cluster is ready Observed Generation: 2 Reason: OperatorClusterReady Status: True Type: OperatorClusterReady Gke On Prem Version: 1.36.0-gke.527 Last Gke On Prem Version: 1.35.300-gke.87 Operator Cluster Status: Control Plane Node Pool Status: Anthos Bare Metal Version: 1.36.0-gke.527 Anthos Bare Metal Versions: 1.36.0-gke.527: 3 Conditions: Last Transition Time: 2026-08-10T21:07:22Z Observed Generation: 11 Reason: PreflightCheckPassed Status: True Type: PreflightCheckSuccessful Last Transition Time: 2026-08-10T21:12:05Z Observed Generation: 11 Reason: NodepoolReady Status: True Type: Ready Last Transition Time: 2026-08-10T21:11:24Z Observed Generation: 11 Reason: ReconciliationCompleted Status: False Type: Reconciling Gke Versions: v1.36.0-gke.2800: 3 Last Reconciliation Time: 2026-08-10T21:28:02Z Maintenance Nodes: 0 Managed Fields: Label Keys: node.kubernetes.io/control-plane node.kubernetes.io/master Node Label Keys: vsphere://abcdef-1: onprem.gke.io/failure-domain-name vmware.cluster.gke.io/machine-name vsphere://abcdef-2: onprem.gke.io/failure-domain-name vmware.cluster.gke.io/machine-name vsphere://abcdef-3: onprem.gke.io/failure-domain-name vmware.cluster.gke.io/machine-name Ready Nodes: 3 Ready Timestamp: 2026-08-10T16:24:02Z Reconciling Nodes: 0 Stalled Nodes: 0 Unknown Nodes: 0 Data Plane Load Balancer Status: Conditions: Last Transition Time: 2026-08-10T16:08:47Z Observed Generation: 1 Reason: ReconciliationCompleted Status: False Type: Reconciling Node Pool Location: load-balancer-nodepool External Manifests Conditions: Last Transition Time: 2026-08-10T16:12:25Z Observed Generation: 2 Reason: ReconciliationCompleted Status: False Type: Reconciling Gke Connect Conditions: Last Transition Time: 2026-08-10T21:11:33Z Observed Generation: 2 Reason: AnthosBareMetalVersion Status: True Type: 1.36.0-gke.527 Last Transition Time: 2026-08-10T21:11:33Z Observed Generation: 2 Reason: ReconciliationCompleted Status: False Type: Reconciling Gke Connect Dependent System Service Conditions: Last Transition Time: 2026-08-10T16:25:26Z Observed Generation: 2 Reason: ReconciliationCompleted Status: False Type: Reconciling Gke Hub Registration Status: Membership: Description: description Name: name Gke Versions: v1.36.0-gke.2800: 6 Kernel Version Conditions: Last Transition Time: 2026-08-10T16:08:53Z Reason: kernelVersionCheckPassed Status: True Type: kernelVersionCheckSuccessful System Service Conditions: Last Transition Time: 2026-08-10T21:04:39Z Observed Generation: 2 Reason: ReconciliationCompleted Status: False Type: Reconciling Events: Type Reason Age From Message
Normal StatusChanged 58m onprem-user-cluster-controller OnPremUserCluster status changed:
- New ClusterState condition: UPGRADING Normal ControlPlaneUpgradeStarted 58m onprem-user-cluster-controller Creating or updating operator NodePool: NodePool is not ready: Condition "Ready" status "False" is not "True", reason: "Reconciling", message: "", lastTransitionTime: 2026-08-10 20:43:53 +0000 UTC Normal StatusChanged 58m onprem-user-cluster-controller OnPremUserCluster status changed:
- New Ready condition: False, CreateOrUpdateOperatorNodePool, Creating or updating operator NodePool: NodePool is not ready: Condition "Ready" status "False" is not "True", reason: "Reconciling", message: "", lastTransitionTime: 2026-08-10 20:43:53 +0000 UTC Normal ControlPlaneUpgradeStarted 58m onprem-user-cluster-controller Creating or updating operator NodePool: NodePool is not ready: Condition "Ready" status "False" is not "True", reason: "Reconciling", message: "", lastTransitionTime: 2026-08-10 20:43:54 +0000 UTC Normal StatusChanged 58m onprem-user-cluster-controller OnPremUserCluster status changed:
- New Ready condition: False, CreateOrUpdateOperatorNodePool, Creating or updating operator NodePool: NodePool is not ready: Condition "Ready" status "False" is not "True", reason: "Reconciling", message: "", lastTransitionTime: 2026-08-10 20:43:54 +0000 UTC Normal ControlPlaneUpgradeStarted 58m onprem-user-cluster-controller Creating or updating operator NodePool: NodePool is not ready: Condition "Ready" status "False" is not "True", reason: "Reconciling", message: "", lastTransitionTime: 2026-08-10 20:44:38 +0000 UTC Normal StatusChanged 58m onprem-user-cluster-controller OnPremUserCluster status changed:
- New Ready condition: False, CreateOrUpdateOperatorNodePool, Creating or updating operator NodePool: NodePool is not ready: Condition "Ready" status "False" is not "True", reason: "Reconciling", message: "", lastTransitionTime: 2026-08-10 20:44:38 +0000 UTC Normal StatusChanged 56m onprem-user-cluster-controller OnPremUserCluster status changed:
- New Ready condition: False, CreateOrUpdateOperatorNodePool, Creating or updating operator NodePool: NodePool is not ready: Condition "Ready" status "False" is not "True", reason: "Reconciling", message: "", lastTransitionTime: 2026-08-10 20:46:33 +0000 UTC Normal StatusChanged 54m (x2 over 56m) onprem-user-cluster-controller OnPremUserCluster status changed:
- New Ready condition: False, CreateOrUpdateOperatorNodePool, Creating or updating operator NodePool: NodePoolClaim is currently in the progress of rolling update: Condition "NodeRecreationUpdateInProgress" ready, reason: "NodeRecreationUpdateInProgress", message: "Cannot further mark old InventoryMachines for recreation due to MinReadyNodesRequired requirement. Current process: There are still old InventoryMachines: [my-uc-cp-99cc4wxzvx8ww829-2 my-uc-cp-99cc4wxzvx8ww829-1]; New ready count (0) does not match desired count (3)" Normal StatusChanged 53m onprem-user-cluster-controller OnPremUserCluster status changed:
- New Ready condition: False, CreateOrUpdateOperatorNodePool, Creating or updating operator NodePool: NodePool is not ready: Condition "Ready" generation 7 hasn't been observed Normal StatusChanged 53m onprem-user-cluster-controller OnPremUserCluster status changed:
- New Ready condition: False, CreateOrUpdateOperatorNodePool, Creating or updating operator NodePool: NodePool is not ready: Condition "Ready" status "False" is not "True", reason: "Reconciling", message: "", lastTransitionTime: 2026-08-10 20:48:58 +0000 UTC Normal StatusChanged 30m (x3 over 58m) onprem-user-cluster-controller OnPremUserCluster status changed:
- New Ready condition: True, ClusterRunning, Cluster is running Normal ControlPlaneUpgradeFinished 30m (x3 over 58m) onprem-user-cluster-controller Operator NodePool is ready Normal StatusChanged 29m (x9 over 47m) onprem-user-cluster-controller (combined from similar events): OnPremUserCluster status changed:
- New Ready condition: False, CreateOrUpdateNodePools, Creating or updating node pools, unready node pools: [my-uc-gke-onprem-mgmt/my-uc], in deletion node pools: [] Normal NodePoolsUpgradeStarted 29m onprem-user-cluster-controller Creating or updating node pools, unready node pools: [my-uc-gke-onprem-mgmt/my-uc], in deletion node pools: [] Normal StatusChanged 13m onprem-user-cluster-controller OnPremUserCluster status changed:
- New GKEOnPremVersion: "1.36.0-gke.527"
- New ClusterState condition: RUNNING
- New Ready condition: True, ClusterRunning, Cluster is running
アップグレードが完了すると、
gkectl list clustersにRUNNINGのSTATEが表示されます。NAMESPACE NAME READY STATE AGE VERSION my-uc-gkeonprem-mgmt my-uc True RUNNING 9h 1.36.0-gke.1
また、アップグレードが完了すると、
gkectl describe clustersによってStatusの下にLast GKE On Prem Versionフィールドが表示されます。例:Status: Cluster State: RUNNING Last GKE On Prem Version: 1.36.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 を実行してクラスタの一般的な問題を確認できます。その結果に基づいて、手動で修正を行うか、Google Cloud サポートに連絡するかを決定できます。
同期アップグレード
gkectl upgrade コマンドは、プリフライト チェックを実行します。プリフライト チェックが不合格の場合、コマンドはブロックされます。障害を修正するか、--skip-preflight-check-blocking フラグを使用する必要があります。重大な不備がないことが確実な場合にのみ、プリフライト チェックをスキップしてください。
管理ワークステーションで次の手順を行います。
1.16 以降のバージョンにアップグレードする場合は、この手順をスキップしてください。
ユーザー クラスタに準備済みの認証情報と非公開レジストリを使用している場合は、ユーザー クラスタをアップグレードする前に、非公開レジストリの認証情報が準備されていることを確認してください。非公開レジストリの認証情報を準備する方法については、ユーザー クラスタの準備済みの認証情報を構成するをご覧ください。
クラスタを診断して、正常であることを確認します。
gkectl diagnose cluster \ --kubeconfig ADMIN_CLUSTER_KUBECONFIG \ --config USER_CLUSTER_CONFIG
コマンドでエラーまたは警告が報告された場合は、クラスタの問題を診断するを参照して、問題を解決してから続行してください。
クラスタをアップグレードします。
gkectl upgrade cluster \ --kubeconfig ADMIN_CLUSTER_KUBECONFIG \ --config USER_CLUSTER_CONFIG
バージョン 1.14.0 以降にアップグレードすると、ユーザー クラスタ用に新しい kubeconfig ファイルが生成され、既存のファイルは上書きされます。ファイル内のクラスタの詳細を表示するには、次のコマンドを実行します。
kubectl config view --kubeconfig USER_CLUSTER_KUBECONFIG
アップグレードを再開する
ユーザー クラスタのアップグレードが中断された場合は、--skip-validation-all フラグを指定して同じアップグレード コマンドを使用すると、ユーザー クラスタのアップグレードを再開できます。
gkectl upgrade cluster \
--kubeconfig ADMIN_CLUSTER_KUBECONFIG \
--config USER_CLUSTER_CONFIG \
--skip-validation-all
Terraform
Google Cloud CLI のコンポーネントを更新します。
gcloud components updateまだ行っていない場合は、GKE On-Prem API に管理クラスタを登録します。クラスタが GKE On-Prem API に登録された後は、この手順を繰り返す必要はありません。
アップグレード先として使用可能なバージョンのリストを取得します。
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新しいバージョンのコンポーネントをダウンロードして、管理クラスタにデプロイします。
gcloud container vmware admin-clusters update ADMIN_CLUSTER_NAME \ --project=PROJECT_ID \ --location=REGION \ --required-platform-version=VERSION
このコマンドは、
--required-platform-versionで指定したバージョンのコンポーネントを管理クラスタにダウンロードし、そのコンポーネントをデプロイします。これらのコンポーネントを使用すると、管理クラスタがそのバージョンのユーザー クラスタを管理できるようになります。ユーザー クラスタの作成に使用した
main.tfファイルで、クラスタ リソースのon_prem_versionを新しいバージョンに変更します。Terraform プランを初期化して作成します。
terraform initGoogle Cloudプロバイダなどの必要なライブラリがインストールされます。
構成を確認し、必要に応じて変更を加えます。
terraform planTerraform プランを適用して、ユーザー クラスタを作成します。
terraform apply
フルバンドルを削除する
フルバンドルをダウンロードした後、gkectl prepare を正常に実行して管理クラスタとすべてのユーザー クラスタをアップグレードしたら、管理ワークステーションのディスク空き容量を節約するために、フルバンドルを削除する必要があります。次のコマンドを実行して、フルバンドルを削除します。
rm /var/lib/gke/bundles/gke-onprem-vsphere-TARGET_VERSION-full.tgz
管理クラスタのアップグレードを再開する
管理クラスタのアップグレードが中断または失敗した場合で、管理クラスタのチェックポイントに、中断前の状態を復元するために必要な状態が含まれている場合は、アップグレードを再開できます。
警告: アップグレードの失敗後は、gkectl repair admin-master で管理コントロール プレーンを修復しないでください。これを行うと、管理クラスタが不正な状態になります。
手順は次のとおりです。
最初のアップグレードの実施を始める前に、管理コントロール プレーンが正常かどうかを確認します。クラスタの問題を診断するをご覧ください。そのトピックで説明されているように、管理クラスタに対して
gkectl diagnose clusterコマンドを実行します。最初のアップグレード試行の前に、管理コントロール プレーンが正常でない場合は、
gkectl repair admin-masterコマンドで管理コントロール プレーンを修復します。アップグレードが中断または失敗した後にアップグレード コマンドを再実行すると、以前のアップグレード試行と同じバンドルとターゲット バージョンが使用されます。
アップグレード コマンドを再実行すると、チェックポイントから管理クラスタの状態が再作成され、アップグレード全体が再実行されます。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 コマンドは、次の手順を実行します。
gkeadmのロールバック バージョンをダウンロードします。- 現在の管理ワークステーションのホーム ディレクトリをバックアップします。
gkeadmのロールバック バージョンを使用して、新しい管理ワークステーションを作成します。- 元の管理ワークステーションを削除します。
アップグレード用に別バージョンのバンドルをインストールする
ワークステーションをアップグレードすると、クラスタのアップグレード用に、対応するバージョンのバンドルがインストールされます。別のバージョンが必要な場合は、次の手順に沿って TARGET_VERSION のバンドルをインストールします。これはアップグレード後のバージョンです。
現在の
gkectlとクラスタのバージョンを確認するには、次のコマンドを実行します。詳細は、フラグ--details/-dを使用して確認してください。gkectl version --kubeconfig ADMIN_CLUSTER_KUBECONFIG --details
出力には、クラスタのバージョンに関する情報が表示されます。
取得した出力に基づいて、次の問題を確認し、必要に応じて修正します。
現在の管理クラスタのバージョンが TARGET_VERSION よりマイナー バージョンで 1 バージョン超低い場合は、すべてのクラスタを TARGET_VERSION より 1 マイナー バージョン低いバージョンにアップグレードします。
gkectlバージョンが 1.11 未満で、1.12.x にアップグレードする場合は、アップグレードを複数回行う必要があります。1.11.x になるまではマイナー バージョンを 1 つずつアップグレードしてから、このトピックの手順に進んでください。gkectlバージョンが TARGET_VERSION より新しいバージョンの場合は、TARGET_VERSION に管理ワークステーションをアップグレードします。
gkectlとクラスタ バージョンがアップグレードに適していると判断した場合は、バンドルをダウンロードします。バンドルの tarball が管理ワークステーションに存在するかどうかを確認します。
stat /var/lib/gke/bundles/gke-onprem-vsphere-TARGET_VERSION.tgz
バンドルが管理ワークステーションにない場合は、ダウンロードします。
gcloud storage cp gs://gke-on-prem-release/gke-onprem-bundle/TARGET_VERSION/gke-onprem-vsphere-TARGET_VERSION.tgz /var/lib/gke/bundles/
バンドルをインストールします。
gkectl prepare --bundle-path /var/lib/gke/bundles/gke-onprem-vsphere-TARGET_VERSION.tgz --kubeconfig ADMIN_CLUSTER_KUBECONFIG
ADMIN_CLUSTER_KUBECONFIG は、kubeconfig ファイルのパスに置き換えます。ファイルが現在のディレクトリにあり、名前が
kubeconfigの場合、このフラグを省略できます。使用可能なクラスタ バージョンを一覧表示し、使用可能なユーザー クラスタ バージョンにターゲット バージョンが含まれていることを確認します。
gkectl version --kubeconfig ADMIN_CLUSTER_KUBECONFIG --details
これで、ターゲット バージョンでユーザー クラスタを作成することや、ユーザー クラスタをターゲット バージョンにアップグレードすることが可能になります。
アップグレード プロセスのトラブルシューティング
推奨するアップグレード プロセスに従って問題が発生した場合は、次の手順で解決することをおすすめします。以下の推奨事項は、バージョン 1.11.x のセットアップをすでに開始しており、推奨のアップグレード プロセスを進めることを前提としています。
クラスタの作成とアップグレードに関するトラブルシューティングをご覧ください。
ユーザー クラスタのアップグレードに関する問題のトラブルシューティング
ユーザー クラスタのアップグレード時にアップグレード バージョンに問題があるとします。今後のパッチリリースで問題が解決することを Google サポートに確認します。次のように進めることができます。
- 本番環境では、引き続き現在のバージョンを使用します。
- リリース時には、非本番環境クラスタでパッチリリースをテストします。
- 問題ないと判断できる場合は、すべての本番環境ユーザー クラスタをパッチリリース バージョンにアップグレードします。
- 管理クラスタをパッチ リリース バージョンにアップグレードします。
管理クラスタのアップグレードに関する問題のトラブルシューティング
管理クラスタのアップグレード中に問題が発生した場合は、Google サポートに連絡して管理クラスタの問題を解決する必要があります。
新しいアップグレード フローを使用すれば、管理クラスタのアップグレードでブロックされることなく、ユーザー クラスタの新機能を利用できます。これにより、必要に応じて管理クラスタのアップグレード頻度を減らすことができます。アップグレード プロセスは次のようになります。
- 本番環境のユーザー クラスタを 1.12.x にアップグレードします。
- 管理クラスタは以前のバージョンのままにして、セキュリティ パッチを引き続き受信します。
- テスト環境で管理クラスタの 1.11.x から 1.12.x へのアップグレードをテストし、問題があれば報告します。
- 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 --kubeconfig USER_CLUSTER_KUBECONFIG \
get poddisruptionbudget --all-namespaces \
-o jsonpath='{range .items[?(@.status.disruptionsAllowed==0)]}{.metadata.namespace}/{.metadata.name}{"\n"}{end}'
USER_CLUSTER_KUBECONFIG は、ユーザー クラスタの kubeconfig ファイルのパスに置き換えます。
一致する Pod がなく、status.expectedPods が 0 の場合、デフォルトの kube-system/log-aggregator PDB と kube-system/prometheus PDB が disruptionsAllowed: 0 とともに出力に表示されます。これらの PDB はノードのドレインをブロックしないため、無視できます。
アップグレードに関するその他の情報
バージョン 1.1.0-gke.6 で有効になっている VMware DRS ルールについて
バージョン 1.1.0-gke.6 以降、Google Distributed Cloud はユーザー クラスタのノードに対して 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 にアップグレードする場合は、反アフィニティ グループを無効にする必要があります。詳細については、Google Distributed Cloud リリースノートのこの既知の問題をご覧ください。
アップグレード中のダウンタイムについて
| リソース | 説明 |
|---|---|
| 管理クラスタ | 管理クラスタが停止しても、ユーザー クラスタのコントロール プレーンとワークロードは、ダウンタイムの原因となった障害の影響を受けない限り引き続き実行されます。 |
| ユーザー クラスタのコントロール プレーン | 通常、ユーザー クラスタ コントロール プレーンには目立ったダウンタイムはありません。ただし、Kubernetes API サーバーへの長時間実行の接続が切断され、再確立する必要がある場合があります。この場合、API 呼び出し元は、接続が確立するまで再試行する必要があります。最悪のケースでは、アップグレード中に最大 1 分間のダウンタイムが発生することがあります。 |
| ユーザー クラスタノード | アップグレードでユーザー クラスタ ノードの変更が必要な場合、Google Distributed Cloud はノードをローリング方式で再作成し、これらのノードで実行されている 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: /home/janedoe/.ssh/gke-admin-workstation Upgraded from (rollback version): v1.10.0-gke.194 To access your admin workstation: ssh -i /home/janedoe/.ssh/gke-admin-workstation ubuntu@172.16.91.21
パラメータを適切に置き換えて、エディタでファイルを作成します。gkeadm が実行されるディレクトリに、VM 名と同じファイル名でファイルを保存します。たとえば、VM 名が admin-ws-janedoe の場合は、ファイルを admin-ws-janedoe として保存します。
次のステップ
gcloud CLI リファレンス ドキュメント
Terraform リファレンス ドキュメント