hyperpod-node-debugger

HyperPod ノードデバッガー

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

IaC に関する注意（変更コマンドと必ず併記）。 クラスター、VPC、SG、サブネット、EKS の設定を変更するコマンド（例：authorize-security-group-*、modify-vpc-attribute、update-cluster、kubectl label/cordon/drain、create namespace、set env daemonset）を提案する場合は、まずクラスター／VPC／SG が Infrastructure-as-Code（CloudFormation、CDK、Terraform、Pulumi）で管理されているか、お客様に確認してください。管理されている場合は、次のように伝えてください。「まず IaC のソースでこの変更を適用し、その後パイプラインからデプロイしてください。コマンドを直接実行するとテンプレートとのドリフトが発生し、次回のスタック更新で上書きされる可能性があります。」問題をただちに修正する必要があり、IaC の変更が後になる場合は、ドリフトが発生していることを明示し、後で整合させるようお客様に伝えてください。

読み取り専用のトリアージ。scripts/triage-cluster.sh（およびヘルパーの check-efa-sg.sh、check-node-reachability.sh、check-vpc-config.sh）は状態を読み取り、各問題を [FAIL] ... → references/node-diagnostics-detail.md § <section> の形式で出力します。お客様からのチケットでよくあるパターンの一覧：references/node-issue-catalog.md。

---

ワークフロー

1. クラスター名、リージョン、問題が疑われるインスタンス ID、ログに記録された正確なエラー文字列を収集します。
2. scripts/triage-cluster.sh を実行します（対象を 1 つのノードに絞るには --node <INSTANCE-ID> を追加します）。
3. すべての [FAIL]／問題のエントリーについて、参照先のセクションを Read します。
4. 検出内容（スクリプトの出力をそのまま転記）、根本原因、インスタンス／SG ID を記入した正確なコマンド、影響範囲（例：「i-xxx を再起動します」「置き換えでボリュームが消去されます」）を提示します。クラスター／VPC／SG／EKS の状態を変更するコマンドについては、対象リソースが IaC で管理されているか確認し、上記の運用ポリシーの注意事項にあるドリフト警告を伝えてください。
5. お客様から明示的な承認を得るまで待ちます。破壊的な操作の順序は、調査 → 再起動 → 置き換えです。
6. トリアージを再実行して解決したことを確認します。解消されていない場合は繰り返します。

手順 1：トリアージ

bash scripts/triage-cluster.sh --cluster <CLUSTER_NAME_OR_ARN> --region <REGION>

# Focus on one node:
bash scripts/triage-cluster.sh --cluster <CLUSTER_NAME_OR_ARN> --region <REGION> --node <INSTANCE_ID>

1 回の実行で収集される情報：クラスターのステータスと NodeRecovery、イベント、ノードごとの健全性（HyperPod と EKS のラベル、Slurm の状態）、VPC／SG のスナップショット、CloudWatch の利用可否、SSM の準備状況、ノード上のリソースチェック（ディスク、メモリ、/dev/shm、OOM、NVMe、時刻同期、SSM エージェント）、Slurm のノードからインスタンスへのマッピング。

タグ：[PASS] 合格 · [FAIL] → references/... の参照先を伴う問題 · [WARN] 注意事項 · [INFO] 情報。優先度：P0 運用を阻害 · P1 性能低下 · P2 情報のみ。

手順 2：シグナルとセクションを照合

イベント（list-cluster-events）— プロビジョニング時：

イベント	セクション
"EFA health checks did not run successfully"（公開ドキュメントに記載されたシグナルの原文）	A: EFA/SG
インスタンスのブートストラップまたはネットワーク設定の誤りに関するイベント	A + B: VPC
ライフサイクルスクリプトの失敗またはタイムアウト	D: Lifecycle
作成時の容量不足または AZ 不一致による失敗	C: Capacity
ハードウェア障害／UnschedulablePendingReplacement	F: Hardware

EKS ラベル：

ラベル	セクション
node-health-status: UnschedulablePendingReplacement	F
node-health-status: UnschedulablePendingReboot	F
deep-health-check-status: Failed	G → F

症状：

症状	セクション
NCCL の初期化／AllReduce でトレーニングが停止する	A → E
Slurm ノードが down ／「Node unexpectedly rebooted」	H: Slurm
ジョブが PENDING ／COMPLETING のまま停止する	H
自動修復がトリガーされない	F
GPU が認識されない／XID／ECC エラー	G
GPU の行リマップが保留／失敗／サイレント NaN／DCGM Fail	G § G.1.a/b
ディスクフル／OOM／「Cannot allocate memory」	I: Resources
vCPU 数が正しくない（例：p5.48xlarge で 192 ではなく 96）	J: Config
コンテナの CrashLoopBackOff ／ランタイムクラッシュ	M: Container Runtime
aws-node の CrashLoopBackOff ／gRPC 50051 が拒否される	O: CNI / Pod Networking
IP が割り当てられず、Pod が Pending のまま／CNI エラー	O
DNS 解決／enableDnsSupport	B § B.2
パブリックサブネット／IGW の設定ミス	B § B.3
VPC エンドポイント（ECR／STS／FSx）がない	B § B.4
EKS VPC／SG と HyperPod の不一致	B § B.5
カーネルパニック／ウォッチドッグ／ハングしたタスク	N: Kernel
ノード上のシェルが必要	K: SSM
AWS サポート用のログ収集	L: Log Collection

---

A: EFA ／ セキュリティグループ

HyperPod の前提条件ドキュメントに従い、SG では自分自身との間のすべてのインバウンドおよびアウトバウンド通信を許可する必要があります。scripts/check-efa-sg.sh は、クラスター内のすべての SG について自己参照ルールを検証します。ノード上の EFA チェックは、SSM 経由で scripts/check-node-reachability.sh を実行します。詳細：§ A。

B: VPC ／ルーティング

SG／サブネット間の VPC 不一致、S3 ゲートウェイエンドポイントの不足、EKS の認証モード、ワーカーからコントローラーへのルーティング、VPC の DNS サポート、プライベートサブネットと NAT ／ VPC エンドポイント、EKS と HyperPod 間の VPC 整合性を確認します。scripts/check-vpc-config.sh。詳細：§ B。

C：容量／AZ

作成時に容量不足で失敗する場合、または容量に空きがある AZ にサブネットがない場合です。describe-instance-type-offerings で AZ の提供状況を確認し、サブネットの AZ を変更するか、Flexible Training Plans / ODCR を使用してください。詳細：§ C。

D：ライフサイクルスクリプト

クラスターイベントおよび CloudWatch の LifecycleConfig/<group>/<instance-id> に表示されます。よくある原因：S3 への接続、IAM の不足、CRLF の改行、無限ループ、パラメーター名の不一致。詳細：§ D。

E：ソフトウェアバージョン

hyperpod-version-checker に委任して、ノード間の NVIDIA ドライバー、CUDA、NCCL、EFA インストーラー、OFI NCCL、PyTorch を比較してください。ジョブ環境に FI_PROVIDER=efa、FI_EFA_USE_DEVICE_RDMA=1、NCCL_SOCKET_IFNAME=^lo,docker が設定されていることを確認してください。詳細：§ E。

F：ハードウェア／自動修復

NodeRecovery=Automatic を確認し、EKS のヘルスラベルと sagemaker.amazonaws.com/fault-details アノテーションを調べ、CloudWatch ストリーム SagemakerHealthMonitoringAgent/<group>/<instance> を確認してください。HMA は GPU と Neuron の状態をバックグラウンドでパッシブにチェックし、カウントが一致しない場合はノードを再起動します（HMA ドキュメントより：「予期される GPU 数と nvidia-smi が返す数に不一致がある場合、HMA はノードを再起動する」。neuron-ls についても同様です）。手動での復旧順序：まず再起動し、再起動に失敗した場合にのみ置き換えてください。推奨される方法は、バッチ API（BatchReboot／BatchReplaceClusterNodes）です。詳細：§ F · パターン：node-issue-catalog.md。

G：GPU／アクセラレーター

NVIDIA（p4d/p5/g5/g6）： SSM 経由で nvidia-smi と dmesg を使い、Xid、ECC、熱スロットリングを確認します。NVIDIA のカタログに基づく Xid の分類：13 Graphics Engine Exception（アプリケーションレベル）、31 GPU memory page fault（アプリケーション。ドライバー／ハードウェアが原因の場合もあります）、63 GPU memory remapping event（ハードウェア／ECC）、71 CE4 Error（ハードウェアのコピーエンジン）、74 NVLink Error（ハードウェア）、79 GPU has fallen off the bus（PCIe バス）、109 Context Switch Timeout Error（ハードウェア）。訂正不能な ECC が発生した場合は、ノードをドレインして置き換えてください。Row-remap の状態は、潜在的な劣化を示す信頼性の高いシグナルです（§ G.1.a）。

Trainium / Inferentia（trn1/trn2/inf2）： Neuron SDK の neuron-ls、neuron-top、neuron-monitor を使用します。nvidia-smi は使用できません。

GPU／アクセラレーターの障害は、再起動／置き換えのため § F に引き継がれます。詳細：§ G。

H：Slurm ノード管理

ノードがダウン／応答しない、予期しない再起動、ジョブが PENDING／COMPLETING のまま停止する、Slurm からインスタンス ID への変換などが対象です。主なアクセス方法は SSM です。まず slurmd を診断し、根本原因を修正してから、§ H に従ってノードを起動／再開してください。詳細：§ H。

I：リソース枯渇

ディスクフル（HyperPod のルートボリュームはデフォルトで 100 GB で、作成後に拡張する用途ではありません）、OOM、os.fork() のメモリエラー、/dev/shm の枯渇、inode の枯渇などが対象です。フォーク時のメモリエラーを修正するには、export FI_EFA_USE_HUGE_PAGE=0 を設定してください。大量のデータは /opt/sagemaker（セカンダリ EBS）または /opt/dlami/nvme（インスタンスストア）にリダイレクトしてください。詳細：§ I。

J：設定

p5.48xlarge で 192 ではなく 96 vCPU と表示される場合は、update-cluster で ThreadsPerCore=2 を設定してください。詳細：§ J。

K：SSM 経由のノードアクセス

HyperPod では直接 SSH を使用できません。ターゲット形式は sagemaker-cluster:<CLUSTER_ID>_<GROUP>-<INSTANCE_ID> です。失敗の原因：プラグインがない、プレフィックスが間違っている、IAM、VPC エンドポイント。詳細：§ K。

L：ログ収集

S3 に保存されたバンドルの取得は hyperpod-issue-report に委任してください。主な CloudWatch ストリーム：LifecycleConfig/<group>/<instance-id>、SagemakerHealthMonitoringAgent/<group>/<instance-id>。詳細：§ L。

M：コンテナランタイム

EKS での CrashLoopBackOff、OOMKilled、ImagePullBackOff、RunContainerError。kubectl describe pod とノード上の crictl ps -a、journalctl -u containerd を確認してください。詳細：§ M。

N：カーネルとシステム

カーネルパニック、ウォッチドッグのタイムアウト、ソフトロックアップ、HyperPod のヘルスモニタリングで説明できない予期しない再起動。dmesg | grep -iE 'panic|watchdog|hung_task|NMI' と journalctl -b -1 を確認してください。nvrm 関連の兆候は、NVIDIA ドライバーのクラッシュを示しています。詳細：§ N。

O：CNI／Pod ネットワーキング

VPC CNI（aws-node）の障害、IPAMD エラー、gRPC 127.0.0.1:50051 の接続拒否、FailedCreatePodSandBox により Pending のままの Pod。スクリプトは aws-node、kube-proxy、CoreDNS を自動で確認します。詳細：§ O。

---

前提条件

• HyperPod クラスターのコマンド（describe-cluster、list-cluster-nodes、batch-reboot-cluster-nodes、batch-replace-cluster-nodes）に対応するバージョンの aws CLI v2
• python3、bash 4 以降（スクリプトで連想配列が必要です）
• EKS クラスターに対して認証済みの kubectl（ない場合、K8s の確認はスキップされます）
• ノード上のハードウェア確認用の session-manager-plugin
• unbuffer（expect パッケージに含まれます）— 任意です。ない場合、SSM のノード上プローブはスキップされますが、その他のトリアージは引き続き実行されます。yum install expect／apt install expect でインストールしてください。

デフォルト

• リージョン — 必須です。--region を渡すか、$AWS_DEFAULT_REGION を設定してください。
• 対象範囲 — すべてのノードです。--node <ID> を指定すると、1 台に絞り込めます。
• イベントの対象期間 — 直近の最大 500 件のイベント（100 件ずつ、最大 5 ページ）。
• ノードリストの上限 — 最大 20,000 台のノード（100 台ずつ、最大 200 ページ）。上限に達すると警告します。
• SSM プローブ — ノードごとに 180 秒。スロットリング時は再試行します。
• 色 — TTY 以外では自動的に無効になります。強制的に無効にするには --no-color を指定します。

エラー処理

失敗	スクリプトの動作	お客様への案内
aws sts get-caller-identity が失敗	終了コード 1	「AWS 認証情報を修正して、再実行してください。」
describe-cluster が失敗	リージョン内のクラスターを一覧表示した後、終了コード 1	「クラスター名とリージョンを確認してください。」
sagemaker:*／ec2:*／logs:* の AccessDenied	警告し、Missing IAM permission for <API> を追加して続行	「一覧表示された IAM アクションを許可して、再実行してください。」
kubectl がない、または未認証	K8s の確認をスキップ	「kubectl をインストールして認証してください（§ K を参照）。」
session-manager-plugin がない	ノード上のプローブをスキップ	「session-manager-plugin をインストールしてください（§ K を参照）。」
SSM の start-session が失敗、またはタイムアウト（180 秒）	ノードを到達不能としてマークし、→ § K を案内	「--node <ID> を指定して再実行し、対象を絞り込んでください。ノード上の SSM エージェントも確認してください。」
クラスターが 20,000 台を超える	最初の 20,000 台をページネーションで取得し、警告	「特定のノードを対象にするには --node を使用してください。」

終了コード：0 トリアージ完了 · 1 クラスターが見つからない、または必須の前提条件が不足しています。

IAM のアクセス許可

読み取り専用の診断 — triage-cluster.sh、check-efa-sg.sh、check-vpc-config.sh、check-node-reachability.sh が対象です。

{
  "Action": [
    "sagemaker:DescribeCluster",
    "sagemaker:DescribeClusterNode",
    "sagemaker:ListClusterNodes",
    "sagemaker:ListClusterEvents",
    "sagemaker:ListClusters",
    "eks:DescribeCluster",
    "ec2:DescribeSecurityGroups",
    "ec2:DescribeSubnets",
    "ec2:DescribeVpcs",
    "ec2:DescribeVpcAttribute",
    "ec2:DescribeVpcEndpoints",
    "ec2:DescribeRouteTables",
    "ec2:DescribeNetworkInterfaces",
    "ec2:DescribeInstances",
    "ec2:DescribeInstanceTypeOfferings",
    "ec2:DescribeInstanceTypes",
    "logs:DescribeLogGroups",
    "logs:DescribeLogStreams",
    "logs:FilterLogEvents",
    "ssm:StartSession",
    "ssm:TerminateSession",
    "service-quotas:GetServiceQuota"
  ]
}

sts:GetCallerIdentity は暗黙的に許可されるため、IAM アクションは不要です。HyperPod での SSM は、sagemaker-cluster:<cluster-id>_<group>-<iid> ターゲットに対して start-session を使用します。インスタンス ID のみを指定した send-command は使用しません。修正コマンドを実行する場合は、対応する書き込み権限（例：ec2:AuthorizeSecurityGroupIngress / Egress、ec2:RevokeSecurityGroupIngress / Egress、ec2:ModifyVpcAttribute、sagemaker:UpdateCluster、sagemaker:BatchRebootClusterNodes、sagemaker:BatchReplaceClusterNodes）を付与してください。診断自体には不要です。

スキルの委任

必要な作業	使用するもの
クラスターの作成／デプロイの失敗	hyperpod-cluster-debugger（§ A / B / C / H + --validate）
クラスター全体での SSM 障害	hyperpod-cluster-debugger § F
単一ノードでの SSM 障害	ここで対応 — § K
作成時のクラスター全体での EFA ヘルスチェックの失敗	hyperpod-cluster-debugger § A
プロビジョニング後の単一ノードでの EFA 障害	ここで対応 — § A
NCCL AllReduce／集合演算のタイムアウト（分散処理）	hyperpod-nccl
特定ノードでの GPU のサイレント NaN（row-remap / DCGM）	ここで対応 — § G.1（NCCL で見つかった場合も同様）
デプロイ後のクラスター全体の管理	hyperpod-cluster-debugger
ノード上でのシェル／コマンド	hyperpod-ssm
CUDA / NCCL / EFA のバージョン比較	hyperpod-version-checker
AWS Support 向けの診断バンドル	hyperpod-issue-report
トレーニング性能／MFU の低下	hyperpod-mfu-debugger

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

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

1. SG ルールが正しく、到達性テストも成功するのに EFA が失敗する。
2. VPC は正しいのに K8s のブートストラップに失敗する — VPC フローログで REJECT を確認してください。
3. 交換を繰り返しても失敗するハードウェア障害（物理ホストの不具合）。
4. 有効な ODCR があるにもかかわらず、容量不足を示すシグナルによってノードの交換に失敗する。

ケースを作成する前に

# 1. Cluster identity + affected node status
aws sagemaker describe-cluster --cluster-name <CLUSTER> --region <REGION>
aws sagemaker list-cluster-nodes --cluster-name <CLUSTER> --region <REGION> \
  --query "ClusterNodeSummaries[?InstanceId=='<INSTANCE_ID>']"

# 2. Triage bundle (scoped to the affected node where possible)
bash scripts/triage-cluster.sh --cluster <CLUSTER> --region <REGION> --node <INSTANCE_ID> > triage.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）
• 影響を受けるインスタンス ID／ノード名／インスタンスグループ名
• 障害が発生した時間帯（UTC の開始時刻／終了時刻）
• 確認された正確なエラー文字列（ポッドログ、CloudWatch、dmesg、イベントからそのままコピー）
• ハードウェアが関係する場合は XID 番号／ECC カウント／DCGM の出力
• 上記の手順 2 で作成した triage.txt
• 手順 3 の hyperpod-issue-report バンドルの S3 URI

実際の顧客チケットでのパターン：node-issue-catalog.md。