クラスタ ヘルス スキャナのトラブルシューティング

このドキュメントでは、クラスタ ヘルス スキャナに関する一般的な問題とその解決方法について説明します。

アクティブなワークロードが検出されたため、スキャンがノードをスキップするか、停止する

問題: スキャンで一部の GPU ノードがスキップされるか、TPU ノードプールの事前チェック中に停止し、アクティブなワークロードが検出されたことが報告されます。

原因: 1 つ以上のターゲット ノードでワークロードが実行されています。

解決策: ターゲット ノードのワークロードをドレインまたは停止してから、スキャンを再実行します。詳細については、ターゲット ノードがアイドル状態であることを確認するをご覧ください。

マシンタイプが混在しているため、スキャンが停止する

問題: 事前チェック中にスキャンが停止し、ターゲット ノードが異なるマシンタイプを使用していることが報告されます。

原因: --nodepools フラグで指定したノードプールまたは --partitions フラグで指定したパーティションが、すべて同じマシンタイプを使用しているわけではありません。たとえば、1 回のスキャンで GPU ノードプールと TPU ノードプール、または A3 Mega ノードと A4 ノードを混在させることはできません。

解決策: マシンタイプごとに個別のスキャンを実行します。

ストレージ権限エラーのためスキャンが停止する

問題: 事前チェック中にスキャンが停止し、Cloud Storage エラーが報告されます。

原因: バケットが存在しないか、レポートを書き込むプリンシパルにバケットへの書き込み権限がありません。

解決策: バケットが存在し、プリンシパルにバケットに対する Storage オブジェクト管理者のロールが付与されていることを確認します。詳細については、レポート用の Cloud Storage バケットを設定するをご覧ください。

コマンドライン ツールがクラスタに接続できない

問題: chs コマンドライン ツールが認証エラーまたは接続エラーを返します。

原因: クラスタの kubeconfig エントリがないか、コンテナ内で認証情報を使用できません。

解決策: クラスタまたはインスタンスに接続するの説明に従って、gcloud container clusters get-credentials コマンドを実行します。次に、クラスタ ヘルス スキャナをインストールするの説明に従って、kubeconfig ファイルと Google Cloud 認証情報がコンテナにマウントされていることを確認します。

呼び出し元にプロジェクトにアクセスする権限がない

問題: chs コマンドが次のエラーを返します。

ERROR: The caller doesn't have permission to access the project PROJECT_ID

原因: 認証情報がないか、有効期限が切れているか、アクティブな ID にプロジェクトで必要な Identity and Access Management(IAM)権限がありません。

解決策: ユーザー アカウントを使用してアプリケーションのデフォルト認証情報を設定します。

gcloud auth application-default login

サービス アカウントではなくユーザー アカウントで Google Cloud CLI を認証する必要がある場合は、次のコマンドを実行します。

gcloud auth login --no-browser

GPU テストでドライバまたはハードウェア エラーが報告される

問題: nvidia-smi テストまたは dcgm テストの実行後、ヘルスレポートに一部のノードの DEGRADED ステータスまたは INCOMPLETE ステータスが表示されます。

原因: ノード上の GPU が検出されない、GPU ドライバが動作していない、または NVIDIA データセンター GPU Manager(DCGM)がハードウェア障害を検出した。

解決策: ローカル出力ディレクトリまたは Cloud Storage バケットのワークスペース ディレクトリにある診断ログを確認します。次に、Remediate unhealthy nodes で、環境の手順に沿って操作します。

ネットワーク テストで帯域幅が狭い、またはレイテンシが高いと報告される

問題: ヘルスレポートに、一部のノードの集合通信帯域幅が低いか、レイテンシが高いことが示されています。

原因: GPU の場合、これは 1 つ以上のノードの GPU、NVLink 接続、またはネットワーク インターフェースの不具合が原因です。TPU では、これは 1 つ以上のノードの ICI リンクまたは TPU チップの不具合が原因で発生します。

解決策: GPU の場合は、nccl-pairwise テスト結果を使用して、低速なノードペアに関与しているノードを特定します。TPU の場合は、ヘルスレポートで tpu-collectives と tpu-network-stress の結果を確認します。次に、Remediate unhealthy nodes の手順に沿って操作します。

スキャンが停止した後もリソースがクラスタに残る

問題: chs プロセスが終了した後も、診断ジョブまたはリソースが Google Kubernetes Engine(GKE)クラスタに残っている。

原因: GKE では、スキャンの終了時にリソースをクリーンアップするために、スキャンの実行中、chs プロセスが実行されている必要があります。

解決策: 停止した実行またはクラスタ上のすべての実行をキャンセルして、残りのジョブを削除し、ノードを解放します。

chs cancel RUN_ID

クラスタ上のすべての実行をキャンセルするには、chs cancel --all を実行します。

TPU がビジー状態のときにスタンドアロン TPU インスタンスでスキャンが失敗する

問題: スタンドアロン TPU インスタンスでスキャンを実行すると、chs コマンドライン ツールが TPUs are busy エラーを返します。

原因: TPU インスタンス上の別のプロセスが TPU デバイスを使用しています。

解決策: 他のプロセスが完了するまで待つか、プロセスを停止してから、スキャンを再実行します。

スタンドアロン TPU インスタンスで memlock 制限エラーが発生してスキャンが失敗する

問題: スタンドアロン TPU インスタンスでスキャンを実行すると、chs コマンドライン ツールから、memlock の上限が低すぎるか、TPU テストに root または無制限の memlock の上限が必要であることが報告されます。

原因: 現在のユーザー セッションには、制限付きのロックインメモリ アドレス空間(memlock)の上限があります。

解決策: root ユーザーとしてクラスタ ヘルス スキャナを実行するか、スキャンを実行する前に memlock の上限を引き上げます。

ulimit -l unlimited

ホストにアクセスできないスタンドアロン TPU インスタンスでコンテナが失敗する

問題: コンテナ イメージを使用してスタンドアロン TPU インスタンスでスキャンを実行すると、chs コマンドライン ツールが次のエラーで失敗します。

CHS runs in a container without access to the host

原因: TPU インスタンスのスタンドアロン モードでは、コンテナはホスト PID Namespace を共有し、ホスト ファイル システムをマウントして、/dev/vfio の TPU デバイスを検査して使用する必要があります。

解決策: --privileged、--pid=host、-v /:/host フラグを指定してコンテナを起動します。docker run コマンドの全体については、コンテナ イメージ をご覧ください。

パッケージのインストールが Python バージョン エラーで失敗する

問題: pip install を実行すると、エラー Package 'chs' requires a different Python が発生して失敗する。

原因: マシンの python3 バージョンが 3.12 より前です。これは、Slurm ログインノードと TPU インスタンスで一般的です。

解決策: uv を使用して Python 3.12 仮想環境を作成し、root 権限なしでクラスタ ヘルス スキャナをインストールします。

python3 -m venv uv-venv
uv-venv/bin/pip install uv
uv-venv/bin/uv venv --python 3.12 chs-venv
source chs-venv/bin/activate
uv-venv/bin/uv pip install git+https://github.com/GoogleCloudPlatform/cluster-health-scanner.git

TPU テストの依存関係がインストールされていないため、スキャンでスタンドアロン TPU インスタンスがスキップされる

問題: スタンドアロン TPU インスタンスでスキャンを実行すると、chs run はインスタンスをスキップし、次の警告を返します。

The TPU test dependencies are not installed. CHS installs them only on Linux x86_64 with Python 3.12.

原因: クラスタ ヘルス スキャナの Python パッケージが、3.12 以外の Python バージョン(Python 3.13 など)でインストールされています。スタンドアロン TPU インスタンスでは、TPU ベンチマークの依存関係は、Python 3.12 を使用する Linux x86_64 にのみインストールされます。

解決策: uv を使用して Python 3.12 仮想環境にクラスタ ヘルス スキャナを再インストールするか(Python バージョン エラーでパッケージのインストールが失敗するを参照)、クラスタ ヘルス スキャナのコンテナ イメージを使用します。