hyperpod-cluster-debugger

HyperPod 集群调试器

操作策略。 自行运行只读诊断。切勿运行会更改集群、节点或工作负载状态的命令——请将每条命令作为 建议命令（请自行运行） 代码块呈现，并等待客户运行。破坏性操作顺序：调查 → 重启 → 替换（替换会销毁根卷和辅助卷；不支持用于 Slurm 控制器节点）。

运行任何会更改状态的 CLI 前：询问是否由 IaC 管理。 HyperPod 集群、安全组、EKS 访问条目和 IAM 通常通过 CloudFormation / CDK / Terraform 进行预置。如果是，修复应在 IaC 中完成——运行 CLI 会造成配置漂移，下次部署时更改会被还原。仅在无法使用 IaC 时使用 CLI（无法访问、早于 IaC、正在审核中）。

scripts/diagnose-cluster.sh 为只读脚本：它通过 AWS API（以及通过 SSM 检查 Slurm 控制器健康状况）收集状态，并将每个问题打印为 [FAIL] ... → references/<file>.md § <section>。

参考文档	在以下情况打开
cluster-diagnostics-detail.md	查看每项诊断结果的修复操作手册（§ A–L）
cluster-operations.md	查看运维深入指南（EFA 安全组、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]，读取所引用的章节。
4. 提供诊断结果、根因和原样的建议命令代码块。等待客户批准。
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——这会启用按可用区进行的容量检查（如果提供的子网中没有任何子网位于支持该实例类型的可用区，则会发出警告；这会导致创建时容量不足）。

标记：[PASS] · [FAIL]（计入统计，包含 → references/... 指针）· [WARN] · [INFO]。优先级：P0 阻止操作 · P1 性能下降 · P2 仅供参考。

---

第 2 步：将信号匹配到章节

错误消息 / 事件：

信号	章节
"EFA health checks did not run successfully"（公开文档中的原文信号）	A：EFA 健康检查
创建时出现容量不足或 AZ 不匹配故障	B：容量与 AZ
预置期间生命周期脚本失败或超时	C：生命周期脚本
kubectl 身份验证错误（服务端要求提供凭证 / 没有 API 组列表）	D：EKS 访问
状态为 InService，但并非所有实例都可见	E：集群预置
"Target is not connected" / SSM 错误	F：SSM 连接
未执行节点替换 / batch-replace 无法正常工作	G：节点替换
"Embedded stack failed" / 任何 CloudFormation 错误	H：CloudFormation 错误
UpdateClusterSoftware 失败或集群处于维护后回滚状态	J：AMI 与集群更新
EKS 中存在悬空 / 孤立节点，与 list-cluster-nodes 的结果不一致	K：悬空节点与清理
HyperPod 附加后 Cluster Autoscaler 出现故障	L：自动扩缩容器兼容性
I/O 缓慢、FSx 吞吐量饱和	cluster-operations.md § 9
Slurm 节点名称 → 实例 ID 查找	I：实用工具

---

A：EFA 健康检查

SG 缺少自引用规则。为集群中的每个 SG 添加入站和出站自引用规则，并为节点所需的 AWS API 配置最小权限出站规则（通过 HTTPS 443 访问 S3 / ECR / SageMaker / SSM / STS / CloudWatch Logs；条件允许时使用 VPC 端点前缀列表）。完整步骤：cluster-diagnostics-detail.md § A。

B：容量与 AZ

请求的 AZ 中没有可用的实例类型。使用 describe-instance-type-offerings 验证，然后更换 AZ、使用 Flexible Training Plans，或申请 ODCR。详情：§ B · 策略：capacity-planning.md。

C：生命周期脚本

预置期间脚本失败或超时。在 /aws/sagemaker/Clusters/<name>/<id> 下查看 CloudWatch 日志——常见原因：缺少 S3 VPC 端点、IAM 权限缺失、CRLF 换行符、实例组名称不匹配。详情：§ C · 目录结构：lifecycle-scripts.md。

D：EKS 访问 / kubectl

IAM 身份未添加到 EKS 访问条目中。使用 sts get-caller-identity 验证，创建具有管理员策略的访问条目，并更新 kubeconfig。详情：§ D。

E：集群预置

在持续预置期间，集群处于 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 表示存在一个或多个严重故障（未找到集群、缺少致命前置条件，或在 diagnose 或 --validate 模式下出现任何 [FAIL]）。[WARN] 行不会影响退出代码。

技能委派

需求	使用
在节点上运行 Shell 命令	hyperpod-ssm
跨节点进行版本比较	hyperpod-version-checker

升级至 AWS Support

在以下情况下升级至 AWS Support：

1. 即使安全组规则正确，EFA 健康检查仍失败。
2. 即使 Flexible Training Plan / ODCR 有效，容量错误仍持续出现。
3. 节点替换反复失败，且没有明确的事件 / 日志信号。
4. 集群长时间处于非终止状态（Creating、Updating 或维护后回滚状态）。
5. CloudFormation 根本原因是内部服务错误。

创建支持案例前

运行以下命令并附上输出。目标：AWS Support 在创建案例时即可获取所有信息。

# 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