hyperpod-nccl

HyperPod NCCL デバッガー

運用ポリシー。 読み取り専用の診断は自分で実行してください。クラスター、ノード、またはワークロードの状態を変更するコマンドは実行しないでください。各コマンドは Suggested command (run this yourself) ブロックとして提示し、お客様の返答を待ってください。破壊的操作の順序は、調査 → 再起動 → 置換です（置換するとルートボリュームとセカンダリボリュームが削除されます。Slurm コントローラーノードではサポートされていません）。推測でトレーニング状態を破棄しないでください。

SageMaker HyperPod（EKS および Slurm）での NCCL 障害を診断します。scripts/nccl-diagnose.sh は AWS API、kubectl、SSM を介して状態を読み取り、各問題を [FAIL] ... → references/<file>.md § <section> として出力します。読み取り専用です。

シグナルの取得元： list-cluster-events が保持するのは、ライフサイクル、ブートストラップ、EFA ヘルスチェック、キャパシティ、置換、再起動、AMI ロールバックなどのインフラストラクチャレベルの状態のみです。NCCL タイムアウト、GPU XID／ECC、ポッド単位のトレーニングシグナルは保持されません。これらはポッドログ、CloudWatch トレーニングストリーム、ノード上の SSM プローブ、NCCL 環境変数の監査から取得します。トレーニング中の NCCL の問題で「イベントなし」となるのは想定どおりであり、異常がないことを示すものではありません。

---

ワークフロー

1. クラスター名、リージョン、名前空間／ジョブ（EKS）、正確な NCCL エラー文字列を収集します。
2. 診断を実行します（必ず実行してください。以降の対応はすべて出力をもとに進めます）。
3. [FAIL] の各行について、参照先のセクションを Read します。
4. スクリプトの出力から具体的な値（インスタンス ID、SG ID、名前空間）を補完したうえで、調査結果、根本原因、Suggested-command ブロックを提示します。お客様の承認を待ってください。
5. 診断を再実行して確認します。

調査結果に該当するセクションがない場合は、バグとして報告してください。修正方法をでっち上げないでください。

ステップ 1：kubectl を認証する（EKS）

EKS_ARN=$(aws sagemaker describe-cluster --cluster-name <HYPERPOD-NAME> --region <REGION> \
  --query 'Orchestrator.Eks.ClusterArn' --output text)
EKS_NAME=$(echo "$EKS_ARN" | awk -F'/' '{print $NF}')
aws eks update-kubeconfig --name "$EKS_NAME" --region <REGION>
kubectl get nodes

ステップ 2：診断を実行する

# Basic:
bash scripts/nccl-diagnose.sh --cluster <HYPERPOD-NAME> --region <REGION>

# Scope to an EKS job/namespace:
bash scripts/nccl-diagnose.sh --cluster <NAME> --region <REGION> --namespace <NS> --job <JOB>

# Force orchestrator:
bash scripts/nccl-diagnose.sh --cluster <NAME> --region <REGION> --orchestrator slurm

# Larger hardware sample (default 3):
bash scripts/nccl-diagnose.sh --cluster <NAME> --region <REGION> --sample-nodes 10

# Specific node only:
bash scripts/nccl-diagnose.sh --cluster <NAME> --region <REGION> --node i-0abc123def456

タグ：[PASS] · [FAIL]（Issues Found にカウントされ、参照先を示します） · [WARN] · [INFO]。優先度：P0 はトレーニングを阻害 · P1 は性能低下 · P2 は情報提供のみです。

---

修復インデックス

スクリプト内の各 [FAIL] 行には、該当するセクションが直接示されています。この表は、手動でトリアージする際の参照用です。

検出事項	セクション
SG のインバウンド／アウトバウンド自己参照がない	operations.md § 8
通信をブロックする NetworkPolicy／全許可ルールがない	operations.md § 8
Slurm ノードが DOWN／DRAINING／RemoveIPC	operations.md § 7
GPU XID／SYSTEM_ERROR／ハードウェア障害	hyperpod-node-debugger § F / § G
GPU の row-remap／DCGM Fail／サイレント NaN	hyperpod-node-debugger § G.1.a/b
NCCL タイムアウト／ランデブー／ストラグラー	debugging-guide.md § 1
EFA の設定／未使用	debugging-guide.md § 6
EFA の TCP フォールバック（NET/OFI Using TCP）	debugging-guide.md § 13
Pod 間の NCCL バージョン不一致	debugging-guide.md § 10
コンテナの OOM（Pod が強制終了、終了コード 137）	debugging-guide.md § 4
GPU の OOM（CUDA out of memory）	debugging-guide.md § 11
RDMA の memlock／/dev/shm の容量不足	debugging-guide.md § 17
MASTER_ADDR の DNS／ヘッドレス Service	debugging-guide.md § 12
NVLS／PXN／トポロジーのチューニング	debugging-guide.md § 19
NCCL／EFA／ランデブーに関するログパターン全般	error-patterns-quick-ref.md
パフォーマンス／nccl-tests／帯域幅	performance-testing.md

---

前提条件

• aws CLI v2.13 以降で認証済み（aws sts get-caller-identity）
• jq、python3、bash 4.2 以降
• unbuffer（expect パッケージからインストール：yum install expect／apt install expect）
• EKS クラスターに対して認証済みの kubectl（存在しない場合、K8s チェックはスキップされます）
• ノード上のハードウェアチェック用の session-manager-plugin

デフォルト

• リージョン — 必須です。--region を渡すか、$AWS_DEFAULT_REGION を設定してください。
• オーケストレーター — 自動検出されます。--orchestrator eks|slurm で上書きできます。
• Namespace／ジョブ（EKS） — すべての Namespace が対象です。--namespace <NS> --job <JOB> で対象を絞り込めます。
• ハードウェアのサンプリング — SSM 経由で 3 ノード（上限 50）を対象にします。特定のノードを指定するには --node <ID> を使用します。ノードのプローブは順次実行されます（ノードあたり 180 秒）。--sample-nodes 10 の場合、約 30 分かかることがあります。
• CloudWatch の期間 — 直近 2 時間です。
• 色 — 非 TTY 環境または TERM=dumb の場合、自動的に無効になります。

エラー処理

失敗	スクリプト	お客様への案内
aws sts get-caller-identity が失敗	AWS エラーとともに終了コード 1	「AWS 認証情報を修正して、再実行してください。」
describe-cluster が AccessDenied	警告を出し、Missing IAM for sagemaker:DescribeCluster を追加	「sagemaker:DescribeCluster を許可してください（operations.md § 2）。」
クラスターが見つからない	リージョン内のクラスターを一覧表示した後、終了コード 1	「HyperPod クラスター名とリージョンを確認してください。」
kubectl がない／認証されていない	警告を出し、K8s チェックをスキップ	「aws eks update-kubeconfig --name <EKS> --region <R> を実行してください。」
SSM プラグインがない	警告を出し、ノード上のハードウェアチェックをスキップ	「session-manager-plugin をインストールしてください。」
SSM がタイムアウトする（180 秒）	部分的な出力を表示し、ノードを到達不能として記録	「--node <ID> --sample-nodes 1 を指定して再実行してください。ノード上の SSM エージェントを確認してください。」
CloudWatch ロググループが見つからない	CloudWatch のスキャンをスキップ	「クラスターで CloudWatch を有効にしてください（operations.md § 4）。」
クラスターイベント API がスロットリングされる	警告を出し、部分的なデータで続行	「後で再実行してください。スクリプトは冪等です。」

終了コード：0 診断完了 · 1 必須の前提条件が不足、またはクラスターに到達できない。

IAM 権限

完全なポリシーと RBAC については、operations.md § 2 を参照してください。HyperPod 上の SSM は、sagemaker-cluster:<cluster-id>_<group>-<iid> ターゲットに対して start-session を使用します。ssm:SendCommand ではなく、ssm:StartSession／ssm:TerminateSession を許可してください。

スケール戦略

スコープ	方法	対象範囲
すべてのノード	sagemaker:ListClusterNodes（ページネーション）	ノードの 100%
すべての K8s オブジェクト	kubectl	ポッド／ノード／ポリシーの 100%
ハードウェア	SSM --sample-nodes N（デフォルト 3）	サンプリング対象
ノードログ	CloudWatch	ノードの 100%

大規模クラスター： PyTorch の NCCL バックエンドでは、デフォルトの collective-op タイムアウトは 10 分です（PyTorch の分散処理ドキュメントを参照）。大規模クラスターでは初回のランデブー時にこの時間を超えることがよくあります。その場合は、torch.distributed.init_process_group(timeout=timedelta(seconds=<N>)) でタイムアウトを延長してください。HyperPod サポートでは、memlock が unlimited の場合に、256 ノード以上のクラスターで NCCL のトポロジーグラフ検索がハングする事例も確認されています。ポッドの securityContext または /etc/security/limits.conf で大きな固定値（例：8388608）を memlock に設定すると、現場でこれらの問題が解消されています。この memlock のパターンは現場での観察に基づくものであり、AWS または NCCL のドキュメントに記載された動作ではありません。

FSDP、DeepSpeed、または Megatron-LM のチューニングについては、debugging-guide.md § 18 を参照してください。

スキルの委任

必要な作業	使用するもの
クラスターの作成／デプロイの失敗	hyperpod-cluster-debugger（§ A / B / C / H + --validate）
デプロイ後のクラスター全体の管理	hyperpod-cluster-debugger
ノードごとの問題（ディスク、ライフサイクル、ハードウェア）	hyperpod-node-debugger
Trainium/Inferentia の集合通信（NCCL ではなく AWS Neuron Collectives）	hyperpod-node-debugger § G.2
ノード上のシェル	hyperpod-ssm
ノード間のバージョン比較	hyperpod-version-checker
AWS Support 向け診断バンドル	hyperpod-issue-report
MFU／パフォーマンスの低下	hyperpod-mfu-debugger

AWS Support へのエスカレーション

次の場合はエスカレーションしてください。

1. すべての SG ルールが正しく、ノード上で EFA を確認済みでも、NCCL がタイムアウトする。
2. すべてのノードでハードウェアチェックに合格しているのに、AllReduce がハングする。
3. Issues Found: 0 でも、トレーニングが失敗する。
4. ノードを交換した後も GPU XID エラーが続く。
5. 集合演算のタイムアウトが発生し、memlock の回避策を適用しても、大規模クラスターのランデブーがハングする。

ケースを作成する前に

# 1. Cluster identity + status
aws sagemaker describe-cluster --cluster-name <C> --region <R>

# 2. Full NCCL diagnostic (sample more nodes for escalation)
bash scripts/nccl-diagnose.sh --cluster <C> --region <R> --sample-nodes 10 > nccl-diag.txt

# 3. Per-node log/config bundle to S3 (delegates to hyperpod-issue-report)
#    See skills/hyperpod-issue-report/SKILL.md for the exact invocation.

ケースに含める情報

• クラスター名 + ARN、AWS リージョン
• オーケストレーター（EKS または Slurm）と EKS クラスター名／Slurm コントローラーノード
• 障害発生の時間帯（UTC の開始／終了時刻）
• 正確な NCCL／libfabric エラー文字列（ポッドログまたは journalctl からそのままコピー）
• 影響を受けたインスタンス ID／ノード名／ポッド名／名前空間／ジョブ名
• 上記の手順 2 で作成した nccl-diag.txt
• 手順 3 の hyperpod-issue-report バンドルの S3 URI
• 適用中の NCCL 環境変数（いずれかのポッドから実行した printenv | grep -E '^NCCL|^FI_|^TORCH_' の出力）

参考資料

• error-patterns-quick-ref.md — ログパターン → コード → 修正方法の表
• debugging-guide.md — シナリオごとの手順（NVLS／PXN／トポロジーを含む 21 セクション）
• performance-testing.md — nccl-tests、帯域幅のしきい値、ストラグラーの検出
• operations.md — IAM、SSM の形式、CloudWatch、環境変数のリファレンス、ノードラベル、Slurm の運用、修正方法