hyperpod-node-debugger

HyperPod 节点调试器

操作策略。 自行运行只读诊断。绝不运行会更改集群、节点或工作负载状态的命令——将每条此类命令作为 建议命令（请自行运行） 代码块提供，并等待客户确认。破坏性操作顺序：调查 → 重启 → 替换（替换会销毁根卷和辅助卷；不支持在 Slurm 控制器节点上执行）。切勿凭猜测丢弃训练状态、日志或缓存。

IaC 说明（始终随变更命令一并提供）。 当你建议运行任何会更改集群、VPC、SG、子网或 EKS 配置的命令时（例如 authorize-security-group-*、modify-vpc-attribute、update-cluster、kubectl label/cordon/drain、create namespace、set env daemonset），先询问客户该集群 / VPC / SG 是否由 Infrastructure-as-Code（CloudFormation、CDK、Terraform、Pulumi）管理。如果是，请告知他们：“请先在 IaC 源中应用此更改，然后通过流水线部署——直接运行命令会导致配置偏离模板，下一次堆栈更新可能会覆盖此更改。”如果他们需要立即修复问题，之后再处理 IaC 变更，请明确指出配置偏离，提醒他们之后进行协调。

只读排查。scripts/triage-cluster.sh（以及辅助脚本 check-efa-sg.sh、check-node-reachability.sh、check-vpc-config.sh）读取状态，并将每个问题打印为 [FAIL] ... → references/node-diagnostics-detail.md § <section>。客户工单模式目录：references/node-issue-catalog.md。

---

工作流

1. 收集集群名称、区域、疑似实例 ID，以及日志中的确切错误字符串。
2. 运行 scripts/triage-cluster.sh（添加 --node <INSTANCE-ID> 以聚焦单个节点）。
3. 对每个 [FAIL] / 问题条目，阅读引用的章节。
4. 提供：脚本检测到的内容（逐字复制该行）、根本原因、填写了实例 / SG ID 的确切命令，以及影响范围（例如“重启 i-xxx”“替换时清除卷”）。对于任何会更改集群 / VPC / SG / EKS 状态的命令，询问受影响的资源是否由 IaC 管理，并说明上述操作策略中的配置偏离警告。
5. 等待客户明确批准。破坏性操作顺序：调查 → 重启 → 替换。
6. 重新运行排查以确认。若问题未解决，则继续迭代。

步骤 1：排查

bash scripts/triage-cluster.sh --cluster <CLUSTER_NAME_OR_ARN> --region <REGION>

# Focus on one node:
bash scripts/triage-cluster.sh --cluster <CLUSTER_NAME_OR_ARN> --region <REGION> --node <INSTANCE_ID>

一次运行即可收集：集群状态和 NodeRecovery、事件、各节点健康状况（HyperPod + EKS 标签、Slurm 状态）、VPC/SG 快照、CloudWatch 可用性、SSM 就绪情况、节点资源检查（磁盘、内存、/dev/shm、OOM、NVMe、时间同步、SSM Agent）、Slurm 节点到实例的映射。

标记：[PASS] 已通过 · [FAIL] 存在问题，并带有 → references/... 指针 · [WARN] 提醒 · [INFO] 信息。优先级：P0 阻止运行 · P1 性能下降 · P2 信息性。

步骤 2：匹配信号 → 章节

事件（list-cluster-events）— 配置期间：

事件	章节
"EFA health checks did not run successfully"（公共文档中的原文信号）	A：EFA/SG
实例引导或网络配置错误事件	A + B：VPC
生命周期脚本失败或超时	D：生命周期
创建时容量不足或 AZ 不匹配故障	C：容量
硬件故障 / UnschedulablePendingReplacement	F：硬件

EKS 标签：

标签	章节
node-health-status: UnschedulablePendingReplacement	F
node-health-status: UnschedulablePendingReboot	F
deep-health-check-status: Failed	G → F

症状：

症状	章节
训练卡在 NCCL 初始化 / AllReduce	A → E
Slurm 节点 down / "Node unexpectedly rebooted"	H: Slurm
作业卡在 PENDING / COMPLETING	H
自动修复未触发	F
GPU 不可见 / XID / ECC 错误	G
GPU 行重映射待处理 / 失败 / 静默 NaN / DCGM Fail	G § G.1.a/b
磁盘已满 / OOM / "Cannot allocate memory"	I: Resources
vCPU 数量错误（例如，p5.48xlarge 上为 96，而非 192）	J: Config
容器 CrashLoopBackOff / 运行时崩溃	M: Container Runtime
aws-node CrashLoopBackOff / gRPC 50051 被拒绝	O: CNI / Pod Networking
Pod 卡在 Pending 且没有 IP / CNI 错误	O
DNS 解析 / enableDnsSupport	B § B.2
公有子网 / IGW 配置错误	B § B.3
缺少 VPC 端点（ECR / STS / FSx）	B § B.4
EKS VPC / SG 与 HyperPod 不匹配	B § B.5
内核崩溃 / 看门狗 / 任务挂起	N: Kernel
需要在节点上使用 shell	K: SSM
为 AWS Support 收集日志	L: Log Collection

---

A：EFA / 安全组

根据 HyperPod 前提条件文档，SG 必须允许所有入站和出站流量访问自身。scripts/check-efa-sg.sh 会验证集群中每个 SG 的自引用规则。通过 SSM 使用 scripts/check-node-reachability.sh 检查节点上的 EFA。完整内容：§ A。

B：VPC / 路由

SG / 子网 VPC 不匹配、缺少 S3 Gateway 端点、EKS 身份验证模式、工作节点到控制器的路由、VPC DNS 支持、私有子网 + NAT / VPC 端点、EKS 与 HyperPod 的 VPC 对齐情况。scripts/check-vpc-config.sh。完整内容：§ B。

C：容量 / AZ

创建时因容量不足而失败，或容量可用的 AZ 中没有子网。通过 describe-instance-type-offerings 检查 AZ 提供情况，然后更改子网 AZ，或使用 Flexible Training Plans / ODCR。完整内容：§ C。

D：生命周期脚本

相关信息会显示在集群事件和 CloudWatch 的 LifecycleConfig/<group>/<instance-id> 下。常见问题：S3 连通性、IAM 权限缺失、CRLF 换行符、无限循环、参数名称不匹配。完整内容：§ D。

E：软件版本

交由 hyperpod-version-checker 比较各节点的 NVIDIA 驱动程序、CUDA、NCCL、EFA 安装程序、OFI NCCL 和 PyTorch。确保作业环境包含 FI_PROVIDER=efa、FI_EFA_USE_DEVICE_RDMA=1、NCCL_SOCKET_IFNAME=^lo,docker。完整内容：§ E。

F：硬件 / 自动修复

确认 NodeRecovery=Automatic，检查 EKS 健康标签和 sagemaker.amazonaws.com/fault-details 注释，并读取 CloudWatch 流 SagemakerHealthMonitoringAgent/<group>/<instance>。HMA 会在后台被动检查 GPU 和 Neuron 状态，并在数量不匹配时重启节点（根据 HMA 文档：“如果预期 GPU 数量……与 nvidia-smi 返回的数量不匹配，HMA 就会重启节点”；neuron-ls 也一样）。手动恢复顺序：先重启，只有重启失败时才替换；首选方式是批处理 API（BatchReboot/BatchReplaceClusterNodes）。完整内容：§ F · 问题模式：node-issue-catalog.md。

G：GPU / 加速器

NVIDIA（p4d/p5/g5/g6）： 通过 SSM 运行 nvidia-smi 和 dmesg，检查 Xid、ECC、热节流。根据 NVIDIA 的目录分类 Xid：13 图形引擎异常（应用级）；31 GPU 内存页错误（应用级，也可能由驱动程序 / 硬件导致）；63 GPU 内存重映射事件（硬件 / ECC）；71 CE4 错误（硬件复制引擎）；74 NVLink 错误（硬件）；79 GPU 已脱离总线（PCIe 总线）；109 上下文切换超时错误（硬件）。任何不可纠正的 ECC 错误都应隔离并替换节点。行重映射状态是静默性能退化的权威信号（§ G.1.a）。

Trainium / Inferentia（trn1/trn2/inf2）： 使用 Neuron SDK 工具 — neuron-ls、neuron-top、neuron-monitor。nvidia-smi 不适用。

GPU / 加速器故障应按 § F 的流程重启 / 替换节点。完整内容：§ G。

H：Slurm 节点管理

节点宕机 / 无响应、意外重启、作业卡在 PENDING/COMPLETING 状态，以及 Slurm 到实例 ID 的转换。主要通过 SSM 访问；先诊断 slurmd，修复根本原因，然后按照 § H 启动 / 恢复节点。完整内容：§ H。

I：资源耗尽

磁盘已满（HyperPod 根卷默认为 100 GB，且不支持在创建后扩容）、OOM、os.fork() 内存错误、/dev/shm 耗尽、inode 耗尽。修复 Fork 内存问题：export FI_EFA_USE_HUGE_PAGE=0。将批量数据重定向到 /opt/sagemaker（辅助 EBS）或 /opt/dlami/nvme（实例存储）。完整内容：§ I。

J：配置

p5.48xlarge 报告的 vCPU 数为 96，而不是 192 → 通过 update-cluster 设置 ThreadsPerCore=2。完整内容：§ J。

K：通过 SSM 访问节点

HyperPod 不支持直接 SSH。目标格式为 sagemaker-cluster:<CLUSTER_ID>_<GROUP>-<INSTANCE_ID>。常见故障：缺少插件、前缀错误、IAM 权限问题、VPC 端点问题。完整内容：§ K。

L：日志收集

交由 hyperpod-issue-report 收集并存储在 S3 中的日志包。重要的 CloudWatch 流：LifecycleConfig/<group>/<instance-id>、SagemakerHealthMonitoringAgent/<group>/<instance-id>。完整内容：§ L。

M：容器运行时

EKS 上出现 CrashLoopBackOff、OOMKilled、ImagePullBackOff、RunContainerError。使用 kubectl describe pod，以及在节点上运行 crictl ps -a、journalctl -u containerd。完整内容：§ M。

N：内核与系统

出现无法通过 HyperPod 健康监控解释的内核崩溃、看门狗超时、软锁定或意外重启。使用 dmesg | grep -iE 'panic|watchdog|hung_task|NMI'，以及 journalctl -b -1。与 nvrm 相关的特征表明 NVIDIA 驱动程序崩溃。完整内容：§ N。

O：CNI / Pod 网络

VPC CNI（aws-node）故障、IPAMD 错误、gRPC 127.0.0.1:50051 连接被拒绝，Pod 因 FailedCreatePodSandBox 卡在 Pending 状态。脚本会自动检查 aws-node、kube-proxy 和 CoreDNS。完整内容：§ O。

---

先决条件

• aws CLI v2，版本需足以支持 HyperPod 集群命令（describe-cluster、list-cluster-nodes、batch-reboot-cluster-nodes、batch-replace-cluster-nodes）
• python3、bash 4+（脚本需要关联数组）
• 已通过身份验证并连接到 EKS 集群的 kubectl（如果缺少，则跳过 K8s 检查）
• 用于节点硬件检查的 session-manager-plugin
• unbuffer（来自 expect 软件包）——可选；如果缺少，则跳过 SSM 节点探测，但仍会运行其余故障排查。使用 yum install expect / apt install expect 安装。

默认值

• 区域——必需：传入 --region 或设置 $AWS_DEFAULT_REGION。
• 目标范围——所有节点；使用 --node <ID> 可指定单个节点。
• 事件时间范围——最多获取最近的 500 条事件（分页，5 × 100）。
• 节点列表上限——最多 20,000 个节点（分页，200 × 100）；达到上限时会发出警告。
• SSM 探测——每个节点 180 s，遇到限流时重试。
• 颜色——在非 TTY 环境下自动禁用；使用 --no-color 可强制关闭。

错误处理

故障	脚本	告知客户
aws sts get-caller-identity 失败	退出码为 1	“修复 AWS 凭证后重新运行。”
describe-cluster 失败	列出区域内的集群后退出，退出码为 1	“确认集群名称和区域。”
sagemaker:* / ec2:* / logs:* AccessDenied	发出警告，添加 Missing IAM permission for <API>，继续	“授予列出的 IAM 操作权限后重新运行。”
kubectl 缺失或未经身份验证	跳过 K8s 检查	“安装 kubectl 并完成身份验证（参见 § K）。”
session-manager-plugin 缺失	跳过节点探测	“安装 session-manager-plugin（参见 § K）。”
SSM start-session 失败或超时（180s）	将节点标记为无法访问，并指向 → § K	“使用 --node <ID> 重新运行以单独排查；检查节点上的 SSM Agent。”
集群超过 20,000 个节点	获取分页结果中的前 20,000 个节点；发出警告	“使用 --node 指定目标节点。”

退出码：0 表示故障排查完成 · 1 表示未找到集群或缺少必需的先决条件。

IAM 权限

只读诊断——涵盖 triage-cluster.sh、check-efa-sg.sh、check-vpc-config.sh 和 check-node-reachability.sh：

{
  "Action": [
    "sagemaker:DescribeCluster",
    "sagemaker:DescribeClusterNode",
    "sagemaker:ListClusterNodes",
    "sagemaker:ListClusterEvents",
    "sagemaker:ListClusters",
    "eks:DescribeCluster",
    "ec2:DescribeSecurityGroups",
    "ec2:DescribeSubnets",
    "ec2:DescribeVpcs",
    "ec2:DescribeVpcAttribute",
    "ec2:DescribeVpcEndpoints",
    "ec2:DescribeRouteTables",
    "ec2:DescribeNetworkInterfaces",
    "ec2:DescribeInstances",
    "ec2:DescribeInstanceTypeOfferings",
    "ec2:DescribeInstanceTypes",
    "logs:DescribeLogGroups",
    "logs:DescribeLogStreams",
    "logs:FilterLogEvents",
    "ssm:StartSession",
    "ssm:TerminateSession",
    "service-quotas:GetServiceQuota"
  ]
}

sts:GetCallerIdentity 是隐式的——无需 IAM 操作。HyperPod 上的 SSM 使用针对 sagemaker-cluster:<cluster-id>_<group>-<iid> 目标的 start-session，而不是针对裸实例 ID 的 send-command。对于修复命令，请授予相应的写入权限（例如 ec2:AuthorizeSecurityGroupIngress / Egress、ec2:RevokeSecurityGroupIngress / Egress、ec2:ModifyVpcAttribute、sagemaker:UpdateCluster、sagemaker:BatchRebootClusterNodes、sagemaker:BatchReplaceClusterNodes）。诊断本身不需要这些权限。

技能委派

需求	使用
集群创建 / 部署失败	hyperpod-cluster-debugger（§ A / B / C / H + --validate）
集群范围的 SSM 中断	hyperpod-cluster-debugger § F
单个节点的 SSM 故障	留在此处——§ K
创建时集群范围的 EFA 健康检查失败	hyperpod-cluster-debugger § A
预置后单个节点的 EFA 故障	留在此处——§ A
NCCL AllReduce / 集合操作超时（分布式）	hyperpod-nccl
特定节点上的静默 GPU NaN（行重映射 / DCGM）	留在此处——§ G.1（即使是通过 NCCL 发现的）
部署后集群范围的管理	hyperpod-cluster-debugger
节点上的 Shell / 命令	hyperpod-ssm
CUDA / NCCL / EFA 版本比较	hyperpod-version-checker
提交给 AWS Support 的诊断包	hyperpod-issue-report
训练性能 / MFU 下降	hyperpod-mfu-debugger

升级至 AWS Support

遇到以下情况时请升级处理：

1. SG 规则正确且可达性检查通过，但 EFA 仍然失败。
2. VPC 配置正确，但 K8s 引导失败——检查 VPC 流日志中是否存在 REJECT。
3. 硬件故障导致替换持续失败（物理主机故障）。
4. 即使 ODCR 有效，节点替换仍因容量不足信号而失败。

开始提交工单前

# 1. Cluster identity + affected node status
aws sagemaker describe-cluster --cluster-name <CLUSTER> --region <REGION>
aws sagemaker list-cluster-nodes --cluster-name <CLUSTER> --region <REGION> \
  --query "ClusterNodeSummaries[?InstanceId=='<INSTANCE_ID>']"

# 2. Triage bundle (scoped to the affected node where possible)
bash scripts/triage-cluster.sh --cluster <CLUSTER> --region <REGION> --node <INSTANCE_ID> > triage.txt

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

在工单中提供

• 集群名称 + ARN 和 AWS 区域
• 编排器（EKS 或 Slurm）
• 受影响的实例 ID / 节点名称 / 实例组名称
• 故障时间范围（UTC 开始 / 结束）
• 观察到的确切错误字符串（从 Pod 日志、CloudWatch、dmesg、事件中逐字复制）
• 硬件相关情况下的 XID 编号 / ECC 计数 / DCGM 输出
• 上述步骤 2 中的 triage.txt
• 步骤 3 中 hyperpod-issue-report 诊断包的 S3 URI

真实客户工单中的问题模式：node-issue-catalog.md。