hyperpod-cluster-debugger
Diagnose and remediate cluster-wide HyperPod (EKS or Slurm) problems — creation / deployment failures (CloudFormation, EFA health check, lifecycle scripts, capacity), EKS access, node replacement, CloudFormation nested-stack errors, post-maintenance rollback state, dangling nodes, autoscaler conflicts. Includes `--validate` pre-flight. Read-only.
Profile →npx skills add awslabs/agent-plugins --skill hyperpod-cluster-debugger --agent claude-code
Same command for any agent — swap --agent for codex, cursor, copilot.
Weekly change comes from our own snapshots, not the repository page — it measures attention, not adoption.
# HyperPod Cluster 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 to run it. Destructive order: **investigate → reboot → replace** (replace destroys root + secondary volumes; not supported on Slurm controller nodes). **Before any state-changing CLI: ask if it's IaC-managed.** HyperPod clusters, SGs, EKS access entries, and IAM are usually provisioned via CloudFormation / CDK / Terraform. If yes, the fix belongs in IaC — running the CLI will drift and the next deploy reverts it. Use the CLI only when IaC is unavailable (locked out, predates IaC, mid-review). `scripts/diagnose-cluster.sh` is read-only: it collects state via AWS APIs (and SSM for Slurm controller health) and prints each issue as `[FAIL] ... → references/<file>.md § <section>`. | Reference | Open when | | ------------------------------------------------------------------------- | ------------------------------------------------------------------- | | [cluster-diagnostics-detail.md](references/cluster-diagnostics-detail.md) | Per-finding r
- Workflow
- Step 1: Run diagnostics
- Step 2: Match signal → section
- A: EFA Health Checks
- B: Capacity & AZ
- C: Lifecycle Scripts
- D: EKS Access / kubectl
- E: Cluster Provisioning
- F: SSM Connectivity
- G: Node Replacement
- H: CloudFormation Errors
- I: Utilities
- J: AMI & Cluster Updates
- K: Dangling Nodes & Cleanup
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> \ aws sagemaker describe-cluster --cluster-name <CLUSTER> --region <REGION> bash scripts/diagnose-cluster.sh --cluster <CLUSTER> --region <REGION> > diag.txt See skills/hyperpod-issue-report/SKILL.md for the exact invocation.
What does the hyperpod-cluster-debugger skill do?
Diagnose and remediate cluster-wide HyperPod (EKS or Slurm) problems — creation / deployment failures (CloudFormation, EFA health check, lifecycle scripts, capacity), EKS access, node replacement, CloudFormation nested-stack errors, post-maintenance rollback state, dangling nodes, autoscaler conflicts. Includes `--validate` pre-flight. Read-only.
How do I install it?
Run `npx skills add awslabs/agent-plugins --skill hyperpod-cluster-debugger --agent claude-code` — it drops the skill into your project so the agent can pick it up. Swap the --agent value for codex, cursor or copilot if you use one of those.
Where does this skill come from?
From awslabs/agent-plugins, a repository with 850 stars. We read it straight from the repository tree rather than a submitted listing, so what you see here is what is actually published.
Is a popular skill a good skill?
Not necessarily. Stars measure attention, not adoption — a repository can trend for a week and be abandoned. That is why we show the weekly change from our own snapshots next to the total, instead of a single flattering number.