HyperPod Issue Report 用于从 AWS SageMaker HyperPod 集群收集诊断日志，生成综合问题报告，以支持故障排查和向 AWS 支持提交信息。它支持 EKS 和 Slurm 两种集群类型，并可自动检测。收集过程通过 SSM 在集群节点上执行，结果存储到 S3。工具使用内置的 scripts/hyperpod_issue_report.py 脚本进行可靠的并行收集。
主要能力
- 从 HyperPod 集群节点通过 SSM 收集诊断日志与配置。
- 将收集结果存储到指定的 S3 路径。
- 支持 EKS 和 Slurm 集群，并自动检测集群类型。
- 使用内置脚本进行并行收集，提升效率。
- 收集完成后展示统计信息，并提供交互式下载。
使用方式 前置条件：
- 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 步）。
工作流：
- 收集信息：从用户处获取集群标识符（必填，接受集群名称或完整集群 ARN，例如 arn:aws:sagemaker:us-west-2:123456789012:cluster/abc123）、AWS 区域（必填，除非可从 ARN 提取）、用于存储报告的 S3 路径（必填，例如 s3://bucket/prefix；如果用户没有存储桶，可创建一个，例如 s3://hyperpod-diagnostics-<account-id>-<region>）、问题描述（可选）、目标范围：所有节点、特定实例组或特定节点 ID（可选）。
- 验证环境：运行 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）：确保 kubectl 已安装（which kubectl），如果缺失，为当前平台安装；使用 describe-cluster 响应中的 EKS 集群名称配置 kubeconfig：aws eks update-kubeconfig --name <eks-cluster-name> --region <region>。
- 运行收集脚本：uv run scripts/hyperpod_issue_report.py --cluster <cluster-name-or-arn> --region <region> --s3-path s3://<bucket>[/prefix]。使用 --help 查看所有选项，包括 --instance-groups、--nodes、--max-workers 和 --debug。注意：--instance-groups 和 --nodes 互斥。节点标识符接受实例 ID（i-）、EKS 名称（hyperpod-i-）或 Slurm 名称（ip-*）。
- 展示结果：收集完成后，脚本显示统计信息并提供交互式下载。报告 S3 位置，并提供以下选项：将报告下载到本地、帮助分析收集的诊断信息（参见 references/collection-details.md 了解每个文件的内容）、为 AWS Support 准备摘要。
故障排查：参见 references/troubleshooting.md 了解错误处理、大型集群调优和已知限制。
适用场景
- 需要对 HyperPod 集群进行故障排查时。
- 需要向 AWS 支持提交诊断信息时。
- 需要收集集群节点日志和配置以进行分析时。
限制
- 需要满足前置条件，包括 AWS CLI 权限、Python 3.8+、uv、SSM Agent 和 kubectl（EKS 集群）。
- 目标节点 IAM 角色需具备对报告存储桶的 S3 读写权限。
- 其他限制暂未提供。