hyperpod-slurm-debugger

HyperPod Slurm 调试器

仅用于诊断。识别并分类 HyperPod Slurm 集群上的 Slurm 调度器和节点守护进程问题。请勿运行、建议或打印任何会更改状态的命令。 如需修复，请链接至 AWS 或 Slurm 官方文档。

何时调用

当用户报告决策表中的任何症状时调用。

何时不调用

• 集群使用 Orchestrator.Eks —— 调用 hyperpod-node-debugger 或 hyperpod-nccl。
• 单节点硬件故障，但 Slurm 调度器正常 —— 调用 hyperpod-node-debugger。
• 调查 NCCL 训练挂起问题 —— 调用 hyperpod-nccl。
• 无法通过 SSM 访问节点 —— 调用 hyperpod-ssm。

限制

• 只读。请勿运行、建议或打印任何会更改状态的命令。
• 如需修复，请链接至 AWS 或 Slurm 文档。由用户授权并执行。
• 由 IaC 管理的集群（Terraform / CloudFormation / CDK）：警告用户，直接修改会导致实时状态与 IaC 计划不一致。

规范恢复链接： references/slurm-details.md → 权威恢复文档。

前提条件

• AWS CLI v2，已通过身份验证，可访问目标账户和区域，并具有以下权限：
  • sagemaker:DescribeCluster、sagemaker:ListClusterNodes
  • 对 HyperPod 创建的 SSM 文档具有 ssm:StartSession 权限
• 本地已安装 Session Manager 插件。
• jq ≥ 1.6。
• unbuffer（来自 expect 软件包）。此项必需——若缺少，aws ssm start-session 会间歇性地返回空标准输出，并显示 Cannot perform start session: EOF，导致每项检查都静默地报告错误结果。安装方法：在 Amazon Linux / RHEL / Debian / Ubuntu / macOS 上安装 expect 软件包。若缺少此项，脚本会在前提条件检查时退出。

操作步骤

步骤 1 — 收集输入信息

向用户询问：

1. HyperPod 集群名称（不是 Slurm 分区名称）。
2. AWS 区域。
3. 可选：特定的 Slurm 节点名称。

步骤 2 — 确认编排器

aws sagemaker describe-cluster --cluster-name <NAME/ARN> --region <REGION> \
  --query 'Orchestrator' --output json

如果存在 Orchestrator.Eks，则停止。根据何时不调用进行转接。

步骤 3 — 运行诊断脚本

bash scripts/slurm-diagnose.sh --cluster <NAME> --region <REGION>
# Scope to a node:
bash scripts/slurm-diagnose.sh --cluster <NAME> --region <REGION> --node <SLURM_NODE>

将脚本输出原样转发给用户。

步骤 4 — 将发现的问题映射到文档

对于每项发现，请在决策表中查找对应章节，并向用户提供相应 AWS / Slurm 文档链接。请勿输入修复命令。

决策表

症状（sinfo -o "%N %T %30E" 或脚本发现）	章节
节点状态 = down 或 down*，原因不属于下列情况	A：节点宕机
节点状态 = down*，Reason = Node unexpectedly rebooted	B：意外重启
节点处于空闲状态时，作业仍为 PENDING 且 REASON=Resources	C：控制器状态
更换节点后，作业卡在 COMPLETING 状态	C：控制器状态
scontrol ping 对控制器返回 DOWN	C：控制器状态
GRES（GPU）计数不正确或未释放	C：控制器状态
已发出 state=fail，但未恢复	D：操作与原因不匹配
会计错误或 RPC 错误提及 dbd	C：控制器状态（slurmdbd）
已编辑 slurm.conf；新分区或节点不可见	C：控制器状态（配置）
作业因硬件故障退出，但未重启	E：自动恢复

默认值

行为	默认值	覆盖方式
模式	始终为只读；不存在修复标志	不适用
区域	$AWS_DEFAULT_REGION，未设置时使用 us-east-1	--region <R>
范围	所有状态为 down / drain / fail /“意外重启”的节点	--node <SLURM_NODE_NAME>
输出	彩色终端	--no-color
SSM 目标格式	sagemaker-cluster:<clusterId>_<instanceGroupName>-<instanceId>（派生得出）	不适用
控制器发现	--controller-group（如果已设置）→ SlurmConfig.NodeType=Controller → provisioning_parameters.json	--controller-group <N>

错误处理

故障	工具行为	所需用户操作
describe-cluster 失败	打印 AWS 错误；退出码为 1	修复凭证/区域；验证集群名称
集群包含 Orchestrator.Eks	退出码为 1，并指向 EKS 侧技能	使用 hyperpod-node-debugger 或 hyperpod-nccl
缺少 session-manager-plugin / SSM 无法访问	sinfo 返回空结果；退出码为 1	安装插件；确认节点状态为 InService
down 节点的磁盘使用率 ≥ 95 %	报告发现项 disk-full-<node>	参阅 AWS 故障排除文档
缺少 jq 或 aws	在先决条件检查时退出码为 1	按照先决条件安装

---

A：节点宕机

节点处于 down 状态，因为 slurmd 已停止响应。原因：slurmd 崩溃、磁盘已满、 OOM、网络分区、硬件故障。

脚本检查：systemctl is-active slurmd、srun -w <NODE> hostname（RPC 层）、磁盘、 内存。

链接：https://github.com/aws/sagemaker-hyperpod-cluster-setup/blob/troubleshooting-doc-20250917/troubleshoot/index.md

如果手动恢复后节点再次变为 down → 升级至 hyperpod-node-debugger。

上下文：references/slurm-details.md § A。

---

B：意外重启

节点处于 down* 状态，原因是 "Node unexpectedly rebooted"，这是因为 slurmd 在带外重启后重新注册。这是上游 Slurm 的行为，并非 HyperPod 所致。 节点通常运行正常。

链接：

• https://github.com/aws/sagemaker-hyperpod-cluster-setup/blob/troubleshooting-doc-20250917/troubleshoot/index.md
• https://slurm.schedmd.com/scontrol.html（state=resume 语义）

如果节点在几分钟内再次重启 → 升级至 hyperpod-node-debugger。

上下文：references/slurm-details.md § B。

---

C：控制器状态

slurmctld 的内存状态可能与磁盘上的状态不同步。重启控制器会从 StateSaveLocation 重新加载状态，并清除异常缓存。由用户决定是否重启并执行操作。

以下情况重启可能有帮助：

症状	原因
PENDING 且 REASON=Resources，节点空闲	重新评估队列
更换节点后作业卡在 COMPLETING	控制器仍持有对旧节点的引用
作业结束后 GRES（GPU、EFA）未释放	资源核算不同步
重启后节点卡在 Unknown，但 slurmd 已运行	未处理重新注册
scontrol ping 超时	控制器事件循环挂起
与 slurmdbd 连接断开 / RPC 错误	DBD 连接卡住

以下情况不要重启：

• 任意节点正在进行 HyperPod 替换（Action:Replace）——并发更改会导致替换失败。
• 只有一个计算节点异常——在该节点上重启 slurmd。
• sinfo 和 squeue 响应正常——问题出在其他地方。
• 尚未检查 journalctl -u slurmctld——panic / OOM 问题会再次出现。
• 刚编辑过 slurm.conf——先尝试 scontrol reconfigure。

折叠触发条件

• slurmdbd 已断开连接——sacct 失败，核算字段显示 Unknown，控制器日志反复显示 Unable to contact slurmdbd。考虑重启控制器之前，先恢复 slurmdbd。 https://slurm.schedmd.com/accounting.html · 详情。
• 配置过期——slurm.conf / topology.conf 的修改时间晚于 slurmctld 启动时间。 先运行 scontrol reconfigure；重启是备用方案。 https://slurm.schedmd.com/scontrol.html · 详情。

重启流程 / 保留内容：

• https://slurm.schedmd.com/slurmctld.html
• https://github.com/aws/sagemaker-hyperpod-cluster-setup/blob/troubleshooting-doc-20250917/troubleshoot/index.md

背景：references/slurm-details.md § C。

---

D：操作原因不匹配

执行 scontrol update state=fail reason=... 时，使用的 reason 与 Action:Reboot 或 Action:Replace 不完全匹配。HyperPod 会静默忽略其他值。脚本会检测处于 fail 状态的节点上相近但不匹配的值。

必需字符串（区分大小写，不含空格和标点）：

• Action:Reboot
• Action:Replace

链接：https://docs.aws.amazon.com/sagemaker/latest/dg/sagemaker-hyperpod-resiliency-slurm-replace-faulty-instance.html

背景：references/slurm-details.md § 操作原因字符串验证。

---

E：自动恢复

--auto-resume=1 是 srun 步骤选项。HMA（健康监控 Agent）标记节点并由自动节点恢复功能替换该节点后，此选项会重新运行该步骤。

作业未重启的原因：

• 在 sbatch 而非 srun 上设置了标记——此选项按步骤生效；sbatch 指令会被静默忽略。
• HMA 未标记该节点——故障由应用程序或暂时性问题导致，而非硬件问题。步骤会作为普通 Slurm 故障退出。
• 集群的 NodeRecovery 为 None——故障节点会被标记，但不会被替换。
• 未进行检查点——每次迭代都会从进程起点重新启动步骤。
• AMI 版本早于 HMA 支持版本（于 2025-09-11 发布）——需要更新 AMI / 集群软件。

链接：https://docs.aws.amazon.com/sagemaker/latest/dg/sagemaker-hyperpod-resiliency-slurm-auto-resume.html

背景：references/slurm-details.md § HyperPod 自动恢复。

---

升级处理

条件	下一项技能
手动恢复后，节点很快再次变为 down	hyperpod-node-debugger（硬件）
slurmd 日志中包含 CUDA / NVIDIA / XID 错误	hyperpod-node-debugger § G
磁盘已满或 /dev/shm 空间耗尽	hyperpod-node-debugger § I
无法通过 SSM 访问节点	hyperpod-ssm
尝试 2 次后，重启控制器仍未清除 COMPLETING	hyperpod-issue-report + AWS Support