mcpField
H
hyperpod-slurm-debugger

hyperpod-slurm-debugger

github.com/awslabsクラウド・DevOps93293 回インストール3 週間前に更新
リポジトリ

hyperpod-slurm-debugger について

HyperPod Slurm クラスターのスケジューラーとノードデーモンの問題を診断する、読み取り専用のスキルです。ノード、コントローラー、リソース計上、自動再開に関する検出結果を分類し、状態変更を行わずに AWS または Slurm の資料へ案内します。

主な機能

  1. 01読み取り専用の Slurm 診断
  2. 02ノードとコントローラー状態の確認
  3. 03リソース計上と RPC の問題特定
  4. 04自動再開が機能しない原因の確認
  5. 05検出結果を公式資料に対応付け

活用シーン

  1. 01down または drain 状態のノード調査
  2. 02PENDING または COMPLETING で止まるジョブの診断
  3. 03GPU リソース数の誤りの確認
  4. 04ハードウェア障害後に再開しないジョブの分析

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/awslabs/agent-plugins --skill hyperpod-slurm-debugger

インストール後、Claude Code で/hyperpod-slurm-debuggerを入力して読み込まれたか確認します。

同梱ファイルreferences/slurm-details.mdscripts/slurm-diagnose.sh

詳細

HyperPod Slurm デバッガー

診断専用です。HyperPod Slurm クラスターの Slurm スケジューラーとノードデーモンの問題を特定し、分類します。状態を変更するコマンドは実行、推奨、出力しないでください。修復方法については、AWS または Slurm の公式ドキュメントへのリンクを提示してください。

呼び出すタイミング

ユーザーが判断表に記載された症状を報告した場合に呼び出します。

呼び出さないタイミング

  • クラスターが Orchestrator.Eks の場合は、hyperpod-node-debugger または hyperpod-nccl を呼び出します。
  • Slurm スケジューラーが正常な状態で発生した単一ノードのハードウェア障害の場合は、hyperpod-node-debugger を呼び出します。
  • NCCL のトレーニングハングを調査する場合は、hyperpod-nccl を呼び出します。
  • SSM 経由でノードに到達できない場合は、hyperpod-ssm を呼び出します。

制約

  • 読み取り専用です。状態を変更するコマンドは実行、推奨、出力しないでください。
  • 修復方法を提示する場合は、AWS または Slurm のドキュメントへのリンクを示してください。実行するかどうかはユーザーが判断し、実行します。
  • IaC 管理のクラスター（Terraform／CloudFormation／CDK）の場合、直接変更すると、ライブ状態が IaC プランと乖離することを警告してください。

正式な復旧 URL： references/slurm-details.md → 正式な復旧ドキュメント。

前提条件

  • AWS CLI v2。対象アカウントとリージョンで認証され、次の権限があること：
    • sagemaker:DescribeCluster、sagemaker:ListClusterNodes
    • HyperPod が作成した SSM ドキュメントに対する ssm:StartSession
  • Session Manager プラグイン がローカルにインストールされていること。
  • jq ≥ 1.6。
  • unbuffer（expect パッケージに含まれます）。必須です。これがない場合、aws ssm start-session が Cannot perform start session: EOF とともに空の標準出力を断続的に返し、すべてのチェックが誤った結果を黙って報告します。インストール方法：Amazon Linux／RHEL／Debian／ Ubuntu／macOS では expect パッケージを使用します。不足している場合、スクリプトは前提条件のチェック時に終了します。

手順

ステップ 1 — 入力情報を収集する

ユーザーに次の情報を尋ねます。

  1. HyperPod クラスター名（Slurm パーティション名ではありません）。
  2. AWS リージョン。
  3. 任意：特定の Slurm ノード名。
ステップ 2 — オーケストレーターを確認する
aws sagemaker describe-cluster --cluster-name <NAME/ARN> --region <REGION> \
  --query 'Orchestrator' --output json

Orchestrator.Eks が存在する場合は停止します。呼び出さないタイミングに従って振り分けてください。

ステップ 3 — 診断スクリプトを実行する
bash scripts/slurm-diagnose.sh --cluster <NAME> --region <REGION>
# Scope to a node:
bash scripts/slurm-diagnose.sh --cluster <NAME> --region <REGION> --node <SLURM_NODE>

スクリプトの出力をそのままユーザーに伝えます。

ステップ 4 — 検出結果 → ドキュメントの対応付け

検出結果ごとに、判断表で該当するセクションを確認し、対応する AWS／Slurm ドキュメントへのリンクをユーザーに提示します。修復コマンドを記載しないでください。

判断表

症状（sinfo -o "%N %T %30E" またはスクリプトの検出結果）セクション
ノードの状態 = down または down*、理由は以下に該当しないA: ノードダウン
ノードの状態 = down*、理由 = Node unexpectedly rebootedB: 予期しない再起動
ノードがアイドル状態なのに、ジョブが REASON=Resources で PENDINGC: コントローラーの状態
ノードの置換後、ジョブが COMPLETING のまま停止しているC: コントローラーの状態
scontrol ping でコントローラーが DOWN と返されるC: コントローラーの状態
GRES（GPU）の数が不正、または解放されないC: コントローラーの状態
state=fail が指定されたが、復旧しなかったD: アクション理由の不一致
dbd に関する会計エラーまたは RPC エラーC: コントローラーの状態（slurmdbd）
slurm.conf を編集したが、新しいパーティションまたはノードが表示されないC: コントローラーの状態（設定）
ハードウェア障害でジョブが終了したが、再起動されなかったE: 自動再開

デフォルト設定

動作デフォルト上書き
モード常に読み取り専用 — 修復フラグはありません該当なし
リージョン$AWS_DEFAULT_REGION。設定されていない場合は us-east-1--region <R>
対象範囲down ／ drain ／ fail ／「予期せず再起動した」状態にあるすべてのノード--node <SLURM_NODE_NAME>
出力色付きのターミナル出力--no-color
SSM ターゲット形式sagemaker-cluster:<clusterId>_<instanceGroupName>-<instanceId>（導出）該当なし
コントローラーの検出--controller-group（設定されている場合）→ SlurmConfig.NodeType=Controller → provisioning_parameters.json--controller-group <N>

エラー処理

失敗スキルの動作必要なユーザー操作
describe-cluster が失敗した場合AWS エラーを出力し、終了コード 1 で終了認証情報／リージョンを修正し、クラスター名を確認する
クラスターに Orchestrator.Eks がある場合EKS 側のスキルを案内して終了コード 1 で終了hyperpod-node-debugger または hyperpod-nccl を使用する
session-manager-plugin が見つからない／SSM に到達できない場合sinfo が空を返し、終了コード 1 で終了プラグインをインストールし、ノードが InService であることを確認する
down ノードのディスク使用率が 95 % 以上の場合検出結果 disk-full-<node> を報告するAWS のトラブルシューティングドキュメントを参照する
jq または aws が見つからない場合前提条件の確認時に終了コード 1 で終了前提条件 に従ってインストールする

A: ノード停止

slurmd が応答を停止したため、ノードは down になっています。原因：slurmd のクラッシュ、ディスクの空き容量不足、OOM、ネットワークの分断、ハードウェア障害。

スクリプトによる確認項目：systemctl is-active slurmd、srun -w <NODE> hostname（RPC 層）、ディスク、メモリ。

リンク：https://github.com/aws/sagemaker-hyperpod-cluster-setup/blob/troubleshooting-doc-20250917/troubleshoot/index.md

手動で再開した後にノードが再び down になる場合は、hyperpod-node-debugger にエスカレーションしてください。

コンテキスト：references/slurm-details.md § A。

B: 予期しない再起動

帯域外の再起動後に slurmd が再登録されたため、ノードは Reason "Node unexpectedly rebooted" を伴う down* 状態になっています。これは HyperPod ではなく、Slurm の上流の動作です。通常、ノードは正常です。

リンク：

数分以内にノードが再び再起動する場合は、hyperpod-node-debugger にエスカレーションしてください。

コンテキスト：references/slurm-details.md § B。

C: コントローラーの状態

slurmctld のメモリー内状態は、ディスク上の状態と不整合になることがあります。コントローラーを再起動すると、StateSaveLocation から再読み込みされ、不正なキャッシュがクリアされます。実施するかどうかの判断と実行はユーザーが行います。

再起動が役立つ可能性がある症状：

症状理由
PENDING で REASON=Resources、ノードはアイドル状態キューを再評価します
ノード交換後にジョブが COMPLETING のまま停止するコントローラーが古いノードへの参照を保持しています
ジョブ終了後に GRES（GPU、EFA）が解放されないリソースのアカウンティングに不整合が生じています
再起動後にノードが Unknown のままで、slurmd は稼働中再登録が処理されていません
scontrol ping がタイムアウトするコントローラーのイベントループがハングしています
slurmdbd との接続が失われる／RPC エラーが発生するDBD 接続が停止しています

次の場合は再起動しないでください：

  • いずれかのノードで HyperPod の交換（Action:Replace）が進行中 — 同時変更により 交換が失敗します。
  • 問題があるのが 1 台のコンピュートノードだけ — そのノードの slurmd を再起動してください。
  • sinfo と squeue が応答する — 問題は別の場所にあります。
  • journalctl -u slurmctld をまだ確認していない — panic／OOM は再発します。
  • slurm.conf を編集したばかり — まず scontrol reconfigure を試してください。
折りたたまれたトリガー
  • slurmdbd の切断 — sacct が失敗し、アカウンティングフィールドに Unknown と表示され、 コントローラーログに Unable to contact slurmdbd が繰り返し出力されます。コントローラーの再起動を 検討する前に、slurmdbd を復旧してください。 https://slurm.schedmd.com/accounting.html · 詳細。
  • 古い設定 — slurm.conf／topology.conf の mtime が slurmctld の起動時刻より新しい。 まず scontrol reconfigure を実行してください。再起動は最後の手段です。 https://slurm.schedmd.com/scontrol.html · 詳細。

再起動手順／保持される内容：

コンテキスト：references/slurm-details.md § C。

D: アクション理由の不一致

reason が Action:Reboot または Action:Replace と完全一致しない状態で、 scontrol update state=fail reason=... が実行されました。HyperPod はそれ以外の値を黙って無視します。 スクリプトは fail 状態のノードについて、わずかに異なる値を検出します。

必要な文字列（大文字と小文字を区別、空白なし、句読点なし）：

  • Action:Reboot
  • Action:Replace

リンク：https://docs.aws.amazon.com/sagemaker/latest/dg/sagemaker-hyperpod-resiliency-slurm-replace-faulty-instance.html

コンテキスト：references/slurm-details.md § Action reason-string validation。

E: 自動再開

--auto-resume=1 は srun のステップオプションです。HMA（Health Monitoring Agent）がノードにフラグを設定し、 Automatic node recovery によってノードが交換された後、ステップを再実行します。

ジョブが再起動されなかった理由：

  • フラグが srun ではなく sbatch に指定されている — ステップごとの設定です。sbatch ディレクティブは黙って無視されます。
  • HMA がノードにフラグを設定していない — 障害はハードウェアではなく、アプリケーションまたは一時的なものです。ステップは通常の Slurm 障害として終了します。
  • クラスターの NodeRecovery が None — 故障したノードにはラベルが付けられますが、交換されません。
  • チェックポイント処理がない — ステップは反復のたびにプロセスの最初から再開されます。
  • AMI が HMA サポート（2025-09-11 リリース）より古い — AMI／クラスターソフトウェアの更新が必要です。

リンク：https://docs.aws.amazon.com/sagemaker/latest/dg/sagemaker-hyperpod-resiliency-slurm-auto-resume.html

コンテキスト：references/slurm-details.md § HyperPod auto-resume。

エスカレーション

条件次のスキル
手動で再開した直後にノードが再び down になるhyperpod-node-debugger（ハードウェア）
slurmd のログに CUDA ／ NVIDIA ／ XID エラーが含まれるhyperpod-node-debugger § G
ディスクが満杯、または /dev/shm が枯渇しているhyperpod-node-debugger § I
SSM 経由でノードに到達できないhyperpod-ssm
2 回試してもコントローラーの再起動で COMPLETING が解消されないhyperpod-issue-report ＋ AWS Support

コメント

Markdown 対応