hyperpod-node-debugger

What this skill does

# HyperPod Node Debugger

**Operating policy.** Run read-only diagnostics yourself. Never run a command that changes cluster, node, or workload state — present each one as a **Suggested command (run this yourself)** block and wait for the customer. Destructive order: **investigate → reboot → replace** (replace destroys root + secondary volumes; not supported on Slurm controller nodes). Never discard training state, logs, or caches on speculation.

**IaC note (always include with mutation commands).** When you suggest any command that changes cluster, VPC, SG, subnet, or EKS configuration (e.g. `authorize-security-group-*`, `modify-vpc-attribute`, `update-cluster`, `kubectl label/cordon/drain`, `create namespace`, `set env daemonset`), ask the customer first whether the cluster / VPC / SG is managed by Infrastructure-as-Code (CloudFormation, CDK, Terraform, Pulumi). If yes, tell them: "Apply this change in your IaC source first, then deploy through the pipeline — running the command directly will drift from your template and the next stack update may overwrite it." If they need to fix the issue immediately and the IaC change will follow, flag the drift explicitly so they remember to reconcile.

Read-only triage. `scripts/triage-cluster.sh` (and helpers `check-efa-sg.sh`, `check-node-reachability.sh`, `check-vpc-config.sh`) read state and print each issue as `[FAIL] ... → references/node-diagnostics-detail.md § <section>`. Catalog of customer-ticket patterns: [references/node-issue-catalog.md](references/node-issue-catalog.md).

---

## Workflow

1. Collect cluster name, region, suspect instance ID, exact error string from logs.
2. Run `scripts/triage-cluster.sh` (add `--node <INSTANCE-ID>` to focus one node).
3. For every `[FAIL]` / issue entry, `Read` the referenced section.
4. Present: what script detected (copy the line verbatim), root cause, exact command(s) with instance/SG IDs filled in, blast radius (e.g. "reboots i-xxx", "wipes volumes on replacement"). For any command that mutates cluster/VPC/SG/EKS state, ask whether the affected resource is IaC-managed and surface the drift warning from the operating-policy note above.
5. Wait for explicit customer approval. Destructive order: investigate → reboot → replace.
6. Re-run triage to confirm. Iterate if not cleared.

## Step 1: Triage

```bash
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>
```

One pass collects: cluster status + NodeRecovery, events, per-node health (HyperPod + EKS labels, Slurm states), VPC/SG snapshot, CloudWatch availability, SSM readiness, on-node resource checks (disk, memory, /dev/shm, OOM, NVMe, time sync, SSM agent), Slurm node→instance mapping.

Tags: `[PASS]` passed · `[FAIL]` issue with a `→ references/...` pointer · `[WARN]` advisory · `[INFO]` informational. Priorities: **P0** blocks operation · **P1** degraded · **P2** informational.

## Step 2: Match signal → section

**Events (`list-cluster-events`) — provisioning-time:**

| Event                                                                       | Section                                                         |
| --------------------------------------------------------------------------- | --------------------------------------------------------------- |
| `"EFA health checks did not run successfully"` (public-doc verbatim signal) | **[A: EFA/SG](#a-efa--security-group)**                         |
| Instance bootstrap or network-misconfiguration event                        | **[A](#a-efa--security-group)** + **[B: VPC](#b-vpc--routing)** |
| Lifecycle-script failure or timeout                                         | **[D: Lifecycle](#d-lifecycle-scripts)**                        |
| Insufficient-capacity or AZ-mismatch failure at creation                    | **[C: Capacity](#c-capacity--az)**                              |
| Hardware failure / `UnschedulablePendingReplacement`                        | **[F: Hardware](#f-hardware--auto-repair)**                     |

**EKS labels:**

| Label                                                 | Section                                                          |
| ----------------------------------------------------- | ---------------------------------------------------------------- |
| `node-health-status: UnschedulablePendingReplacement` | **[F](#f-hardware--auto-repair)**                                |
| `node-health-status: UnschedulablePendingReboot`      | **[F](#f-hardware--auto-repair)**                                |
| `deep-health-check-status: Failed`                    | **[G](#g-gpu--accelerator)** → **[F](#f-hardware--auto-repair)** |

**Symptoms:**

| Symptom                                                  | Section                                                         |
| -------------------------------------------------------- | --------------------------------------------------------------- |
| Training hangs at NCCL init / AllReduce                  | **[A](#a-efa--security-group)** → **[E](#e-software-versions)** |
| Slurm node `down` / `"Node unexpectedly rebooted"`       | **[H: Slurm](#h-slurm-node-management)**                        |
| Jobs stuck PENDING / COMPLETING                          | **[H](#h-slurm-node-management)**                               |
| Auto-repair not triggering                               | **[F](#f-hardware--auto-repair)**                               |
| GPU not visible / XID / ECC errors                       | **[G](#g-gpu--accelerator)**                                    |
| GPU row-remap pending/failed / silent NaNs / DCGM Fail   | **[G § G.1.a/b](#g-gpu--accelerator)**                          |
| Disk full / OOM / `"Cannot allocate memory"`             | **[I: Resources](#i-resource-exhaustion)**                      |
| Wrong vCPU count (e.g. 96 instead of 192 on p5.48xlarge) | **[J: Config](#j-configuration)**                               |
| Container CrashLoopBackOff / runtime crash               | **[M: Container Runtime](#m-container-runtime)**                |
| `aws-node` CrashLoopBackOff / gRPC 50051 refused         | **[O: CNI / Pod Networking](#o-cni--pod-networking)**           |
| Pods stuck Pending with no IP / CNI error                | **[O](#o-cni--pod-networking)**                                 |
| DNS resolution / `enableDnsSupport`                      | **[B § B.2](#b-vpc--routing)**                                  |
| Public subnet / IGW misconfigured                        | **[B § B.3](#b-vpc--routing)**                                  |
| Missing VPC endpoints (ECR / STS / FSx)                  | **[B § B.4](#b-vpc--routing)**                                  |
| EKS VPC / SG mismatch with HyperPod                      | **[B § B.5](#b-vpc--routing)**                                  |
| Kernel panic / watchdog / hung task                      | **[N: Kernel](#n-kernel--system)**                              |
| Need shell on a node                                     | **[K: SSM](#k-node-access-via-ssm)**                            |
| Collect logs for AWS Support                             | **[L: Log Collection](#l-log-collection)**                      |

---

## A: EFA / Security Group

Per the HyperPod prerequisites doc, the SG must allow all inbound and outbound to itself. `scripts/check-efa-sg.sh` validates self-ref rules on every cluster SG. On-node EFA check via `scripts/check-node-reachability.sh` over SSM. Full: [§ A](references/node-diagnostics-detail.md#a-efa--security-group).

## B: VPC / Routing

SG/subnet VPC mismatch, missing S3 Gateway endpoint, EKS auth mode, worker→controller routing, VPC DNS support, private-subnet + NAT / VPC endpoints, EKS↔HyperPod VPC alignment. `scripts/check-vpc-config.sh`. Full: [§ B](references/node-diagnostics-detail.md#b-vpc--routing).

## C: Capacity / A