hyperpod-cluster-debugger

HyperPod クラスターのデバッグ

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

状態を変更する CLI を実行する前に、IaC で管理されているか確認してください。 HyperPod クラスター、SG、EKS アクセスエントリ、IAM は、通常 CloudFormation / CDK / Terraform でプロビジョニングされています。IaC で管理されている場合、修正は IaC 側で行う必要があります。CLI を実行するとドリフトが発生し、次回のデプロイで元に戻ります。CLI を使用するのは、IaC を利用できない場合（ロックアウト中、IaC 導入前、レビュー中）のみにしてください。

scripts/diagnose-cluster.sh は読み取り専用です。AWS API（および Slurm コントローラーのヘルスチェックには SSM）を使って状態を収集し、各問題を [FAIL] ... → references/<file>.md § <section> として出力します。

リファレンス	次の場合に開く
cluster-diagnostics-detail.md	各検出事項の修復手順書（§ A–L）
cluster-operations.md	運用の詳細（EFA SG、EKS アクセス、SSM、Slurm、ファイルシステム）
cloudformation-errors.md	§ H でリソースごとの CFN エラーカタログ全体が必要な場合
capacity-planning.md	§ B または --validate で容量やサブネットのサイズが問題になった場合
lifecycle-scripts.md	§ C で特定のライフサイクルエラーが示された場合
iam-permissions.md	診断に必要な IAM ポリシー全体

---

ワークフロー

1. HyperPod クラスター名（EKS 名ではありません）、リージョン、正確なエラー文字列を確認します。
2. scripts/diagnose-cluster.sh を実行します（作成前の確認には --validate を指定します）。
3. [FAIL] の行ごとに、参照先のセクションを Read します。
4. 検出事項、根本原因、Suggested-command ブロックをそのまま提示します。お客様の承認を待ってください。
5. 診断を再実行して確認します。

---

手順 1：診断を実行する

# Diagnose an existing cluster:
bash scripts/diagnose-cluster.sh --cluster <CLUSTER_NAME_OR_ARN> --region <REGION>

# Pre-flight (no cluster needed) — validates SGs, subnets, IAM, VPC endpoints,
# optionally S3 lifecycle scripts and per-AZ capacity:
bash scripts/diagnose-cluster.sh --validate --region <REGION> \
  --sg-ids <sg-1,sg-2> --subnet-ids <sub-1,sub-2> [--iam-role <role-arn>] \
  [--s3-uri s3://<BUCKET>/path/] [--instance-type ml.p5.48xlarge]

対象のインスタンスタイプが分かっている場合は --instance-type を指定してください。AZ ごとの容量チェックが有効になります（指定されたサブネットのいずれもそのタイプを提供する AZ にない場合に警告します。これは作成時の容量不足エラーの原因になります）。

タグ：[PASS]・[FAIL]（カウント対象。→ references/... の参照先あり）・[WARN]・[INFO]。優先度：P0 は運用を妨げます・P1 は性能が低下しています・P2 は情報提供のみです。

---

ステップ 2：シグナル → セクション

エラーメッセージ／イベント：

シグナル	セクション
"EFA health checks did not run successfully"（公開ドキュメントに記載された正確なシグナル）	A: EFA Health Checks
作成時の容量不足または AZ 不一致によるエラー	B: Capacity & AZ
プロビジョニング中のライフサイクルスクリプトの失敗またはタイムアウト	C: Lifecycle Scripts
kubectl の認証エラー（サーバーが認証情報を要求／API グループ一覧がない）	D: EKS Access
InService だが、すべてのインスタンスが表示されない	E: Cluster Provisioning
"Target is not connected"／SSM エラー	F: SSM Connectivity
ノードの置き換えが行われない／batch-replace が機能しない	G: Node Replacement
"Embedded stack failed"／CloudFormation エラー全般	H: CloudFormation Errors
UpdateClusterSoftware の失敗、またはメンテナンス後のロールバック状態のクラスター	J: AMI & Cluster Updates
EKS に孤立／残存するノードがあり、list-cluster-nodes の結果と一致しない	K: Dangling Nodes & Cleanup
HyperPod のアタッチ後に Cluster Autoscaler が機能しなくなる	L: Autoscaler Compatibility
I/O が遅い、FSx のスループットが飽和している	cluster-operations.md § 9
Slurm ノード名 → インスタンス ID の検索	I: Utilities

---

A: EFA Health Checks

SG に自己参照ルールがありません。クラスター内のすべての SG にインバウンドとアウトバウンドの自己参照ルールを追加し、ノードが必要とする AWS API への最小権限のエグレスも設定してください（S3／ECR／SageMaker／SSM／STS／CloudWatch Logs への HTTPS 443。可能な場合は VPC エンドポイントのプレフィックスリストを使用）。手順の全文：cluster-diagnostics-detail.md § A。

B: Capacity & AZ

要求された AZ でインスタンスタイプを利用できません。describe-instance-type-offerings で確認し、AZ の変更、Flexible Training Plans の利用、または ODCR の申請を行ってください。詳細：§ B · 戦略：capacity-planning.md。

C: Lifecycle Scripts

プロビジョニング中にスクリプトが失敗したか、タイムアウトしました。/aws/sagemaker/Clusters/<name>/<id> の CloudWatch ログを確認してください。よくある原因は、S3 VPC エンドポイントの不足、IAM の設定漏れ、CRLF の改行コード、インスタンスグループ名の不一致です。詳細：§ C · 構成：lifecycle-scripts.md。

D: EKS Access / kubectl

IAM アイデンティティが EKS アクセスエントリに含まれていません。sts get-caller-identity で確認し、管理者ポリシーを指定してアクセスエントリを作成し、kubeconfig を更新してください。詳細：§ D。

E: Cluster Provisioning

Continuous Provisioning では、すべてのインスタンスが揃っていない状態で InService になることがあります。エラーはクラスターエラーではなくイベントとして通知されます。Creating／Updating／Deleting の状態から進まない場合は、CFN のネストされたスタック（§ H）、IAM、容量、イベントを確認してください。Deleting の状態から進まない場合は、VPC ENI の依存関係を確認してください。詳細：§ E。

F：SSM 接続

Target is not connected：sagemaker-cluster:<CLUSTER_ID>_<GROUP>-<INSTANCE_ID> の形式を使用してください（EC2 ID をそのまま指定しないでください）。session-manager-plugin をインストールし、ノードが Running であることを確認してください。タイムアウトが発生する場合は、IAM と VPC エンドポイントを確認してください。詳細：§ F。

G：ノードの置き換え

自動修復：NodeRecovery=Automatic を確認し、Health Monitoring Agent（HMA）のログとノードラベル／Slurm の理由を確認して、キャパシティを確認してください。手動の場合：まず再起動し、再起動に失敗した場合のみ置き換えてください。置き換えを行うには、クラスターに対して少なくとも一度 UpdateClusterSoftware を実行してパッチを適用している必要があり、Slurm コントローラーノードは対象にできません。詳細：§ G。

H：CloudFormation エラー

Embedded stack failed では実際のエラーが隠れてしまいます。Events タブで Failed をフィルターし、ネストされたスタックをたどって、スタック以外のリソースに到達してください。CLI：describe-stack-events --query 'StackEvents[?ResourceStatus==\CREATE_FAILED`]'`。SLR の作成失敗と権限境界による拒否についても説明しています。詳細：§ H · カタログ：cloudformation-errors.md。

I：ユーティリティ

list-cluster-nodes またはノード上の /opt/ml/config/resource_config.json を使用して、Slurm ノード名（ip-10-x-y-z）を HyperPod インスタンス ID に対応付けます。詳細：§ I。

J：AMI とクラスターの更新

UpdateClusterSoftware が失敗してロールバックされる、またはクラスターがメンテナンス後のロールバック状態のままになる場合について説明します。一般的な原因は、新しい AMI と互換性のないライフサイクルスクリプト、古すぎる HMA バージョン、ローリング更新に必要なキャパシティの不足です。クラスターにアクティブなノードがある場合は、削除して再作成するのではなく、診断情報を収集してエスカレーションしてください。詳細：§ J。

K：残存ノードとクリーンアップ

kubectl get nodes には表示されるが list-cluster-nodes には表示されないノード（ゴースト EKS ノード）、またはその逆（kubelet に登録されなかった HyperPod ノード）を検出します。このスクリプトは両方のフラグを検出します。詳細：§ K。

L：オートスケーラーとの互換性

Cluster Autoscaler が HyperPod のプロバイダー ID でエラーを起こし、すべてのノードグループのオートスケーリングが停止します。公式に推奨されている回避策はありません。AWS Support にエスカレーションしてください。Karpenter はデフォルトでは HyperPod ノードと競合しません。詳細：§ L。

---

前提条件

• クラスターのアカウントで認証済みの aws CLI v2.13 以降
• jq、python3、bash 4.2 以降
• EKS クラスターで認証済みの kubectl（ない場合、EKS のチェックはスキップされます）
• session-manager-plugin（Slurm コントローラーのヘルスチェックのみ）

IAM ポリシー：references/iam-permissions.md。

デフォルト設定

• リージョン — 必須：--region を渡すか、$AWS_DEFAULT_REGION を設定してください。
• モード — --cluster <NAME>（診断）または --validate（作成前検証）。
• イベント期間 — 最新のイベントを最大 500 件（100 件 × 5 ページ、ページネーションあり）。
• 色 — 非 TTY では自動的に無効になります。無効化を強制するには --no-color を指定してください。

エラー処理

失敗	スクリプト	お客様への案内
aws sts get-caller-identity が失敗する	終了コード 1	「AWS 認証情報を修正して、再実行してください。」
クラスターが見つからない	リージョンのクラスターを一覧表示した後、終了コード 1	「HyperPod クラスター名（EKS ではありません）とリージョンを確認してください。」
sagemaker:* / ec2:* / eks:* / logs:* が拒否される	警告を出し、Missing IAM permission for <API> を追加して続行	「一覧表示された IAM アクションを許可して、再実行してください。」
kubectl がない、または認証されていない	EKS のチェック（アクセスエントリ、アドオン、aws-auth、ノード）をスキップ	「kubectl をインストールし、認証してください。」
session-manager-plugin がない（Slurm）	Slurm コントローラーのプローブをスキップ	「session-manager-plugin をインストールしてください。」
SSM がスロットリングされる、またはタイムアウトする（180s）	バックオフ付きで再試行し、失敗が続く場合は警告を出して続行	「後で再実行してください。スクリプトは冪等です。」
CloudWatch ロググループが見つからない	CloudWatch のチェックをスキップ	「このクラスターでは CloudWatch が設定されていません。」

終了コード：0 重大な失敗なし · 1 重大な失敗が 1 つ以上（クラスターが見つからない、必須の前提条件が欠けている、または diagnose か --validate モードで [FAIL] がある）。[WARN] の行は終了コードに影響しません。

スキルへの委任

必要な作業	使用するもの
ノード上のシェル	hyperpod-ssm
ノード間のバージョン比較	hyperpod-version-checker

AWS サポートへのエスカレーション

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

1. SG ルールが正しいにもかかわらず、EFA のヘルスチェックが失敗する。
2. 有効な Flexible Training Plan / ODCR があるにもかかわらず、キャパシティエラーが解消しない。
3. 明確なイベントやログの兆候がないまま、ノードの置き換えが繰り返し失敗する。
4. クラスターが非終端状態（Creating、Updating、またはメンテナンス後のロールバック状態）で長時間停止している。
5. CloudFormation の根本原因が内部サービスエラーである。

ケースを作成する前に

次のコマンドを実行し、出力を添付してください。ケース作成時に AWS サポートが必要な情報をすべて揃えておくことが目的です。

# 1. Cluster identity + status (confirms region, ARN, orchestrator, instance groups)
aws sagemaker describe-cluster --cluster-name <CLUSTER> --region <REGION>

# 2. Full cluster-level diagnostic bundle
bash scripts/diagnose-cluster.sh --cluster <CLUSTER> --region <REGION> > diag.txt

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

ケースに含める情報

• クラスター名と ARN（または ClusterId のサフィックス）、および AWS リージョン
• describe-cluster の ClusterStatus と FailureMessage
• 障害が発生した時間帯（UTC の開始時刻／終了時刻）
• 確認された正確なエラー文字列（イベント／ログ／コンソールからそのままコピー）
• 影響を受けたインスタンス ID、NodeLogicalId、インスタンスグループ名
• 上記の手順 2 で取得した diag.txt
• 手順 3 で作成した hyperpod-issue-report バンドルの S3 URI