mcpField
H
hyperpod-issue-report

hyperpod-issue-report

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

hyperpod-issue-report について

hyperpod-issue-reportは、AWS HyperPodクラスターノードの診断ログを収集し、レポートをS3に保存するスキルです。EKSとSlurmに対応し、付属のPythonスクリプトで並列収集します。

主な機能

  1. 01EKSとSlurmクラスターに対応
  2. 02クラスター種別の自動検出
  3. 03ログの並列収集
  4. 04S3へのレポート保存
  5. 05ノードやインスタンスグループの選択

活用シーン

  1. 01HyperPodの問題調査用ログの収集
  2. 02指定したクラスターノードの診断情報収集
  3. 03AWS Support向け診断データの準備

インストール

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

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

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

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

references/
collection-details.md
troubleshooting.md
scripts/
hyperpod_issue_report.py

詳細

HyperPod 問題レポート

SSM を介して HyperPod クラスターのノードから診断ログを収集し、結果を S3 に保存します。EKS クラスターと Slurm クラスターの両方に対応しており、自動検出します。信頼性の高い並列収集には、同梱の scripts/hyperpod_issue_report.py を使用します。

前提条件

  • 権限が設定された AWS CLI：sagemaker:DescribeCluster、sagemaker:ListClusterNodes、ssm:StartSession、s3:PutObject、s3:GetObject、eks:DescribeCluster
  • Python 3.8 以降および uv（インストール方法については、uv のインストールに関するドキュメントを参照してください）
  • 対象ノードで SSM Agent が実行されていること。ノードの IAM ロールには、レポートバケットに対する s3:GetObject／s3:PutObject 権限が必要です
  • EKS クラスターの場合：kubectl がインストールされ、設定済みであること（ワークフローのステップ 2 を参照）

ワークフロー

1. 情報を収集する

ユーザーから以下の情報を収集します。

  • クラスター識別子（必須）：クラスター名または完全なクラスター ARN を指定できます（例：arn:aws:sagemaker:us-west-2:123456789012:cluster/abc123）
  • AWS リージョン（必須。ただし ARN から取得できる場合を除く）
  • レポート保存用の S3 パス（必須。例：s3://bucket/prefix）。ユーザーがバケットを持っていない場合は作成します（例：s3://hyperpod-diagnostics-<account-id>-<region>）
  • 問題の説明（任意）
  • 対象範囲：すべてのノード、特定のインスタンスグループ、または特定のノード ID（任意）
2. 環境を確認する
aws sts get-caller-identity
aws sagemaker describe-cluster --cluster-name <name-or-arn> --region <region>

S3 バケットが存在しない場合は、作成します。

aws s3 mb s3://<bucket-name> --region <region>

EKS クラスターの場合（describe-cluster の出力で Orchestrator.Eks を確認します）：

  1. kubectl がインストールされていることを確認します（which kubectl）。インストールされていない場合は、現在のプラットフォーム用にインストールします。

  2. describe-cluster のレスポンスにある EKS クラスター名を使用して kubeconfig を設定します。

    aws eks update-kubeconfig --name <eks-cluster-name> --region <region>
3. 収集スクリプトを実行する
uv run scripts/hyperpod_issue_report.py \
  --cluster <cluster-name-or-arn> \
  --region <region> \
  --s3-path s3://<bucket>[/prefix]

--instance-groups、--nodes、--max-workers、--debug など、すべてのオプションを確認するには --help を使用します。注：--instance-groups と --nodes は同時に指定できません。ノード識別子には、インスタンス ID（i-*）、EKS 名（hyperpod-i-*）、または Slurm 名（ip-*）を指定できます。

4. 結果を提示する

収集後、スクリプトは統計情報を表示し、対話形式でのダウンロードを案内します。S3 の保存場所を伝え、以下の対応を提案します。

  • レポートをローカルにダウンロードする
  • 収集した診断情報の分析を支援する（各ファイルの内容については references/collection-details.md を参照してください）
  • AWS Support に提出するサマリーを作成する

トラブルシューティング

エラー処理、大規模クラスターの調整、既知の制限事項については、references/troubleshooting.md を参照してください。

コメント

Markdown 対応