hyperpod-cluster-debugger

Diagnose and remediate SageMaker HyperPod cluster issues with AWS tooling.

15|9|Updated Aug 16, 2025
One-click install
npx skills add https://github.com/haozhx23/HyperPod-InstantStart --skill hyperpod-cluster-debugger
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: hyperpod-cluster-debugger
Source: https://github.com/haozhx23/HyperPod-InstantStart/tree/main/.claude/skills/hyperpod-cluster-debugger
Command: npx skills add https://github.com/haozhx23/HyperPod-InstantStart --skill hyperpod-cluster-debugger

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires aws, jq, python3, bash, kubectl, session-manager-plugin, and includes scripts (resource) and references (resource) and assets (resource) components.

What problem does it solve?

This Skill helps diagnose and remediate HyperPod cluster issues, streamlining the management of ML infrastructure.

Core Features & Use Cases

  • Cluster Diagnostics: Identifies and reports on cluster-wide issues, including creation failures, access issues, node replacement challenges, and CloudFormation errors.
  • Pre-flight Validation: Checks the configuration of security groups, subnets, IAM roles, VPC endpoints, and S3 lifecycle scripts before cluster creation.
  • Automated Remediation: Provides detailed remediation steps and suggested commands for common issues, such as EFA health checks, lifecycle script failures, and EKS access problems.

Quick Start

Run the diagnostic for your HyperPod cluster with the following command:

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

Frequently Asked Questions about hyperpod-cluster-debugger

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I diagnose SageMaker HyperPod cluster creation failures and CloudFormation errors?

Diagnose SageMaker HyperPod cluster creation failures by running a diagnostic script that checks security groups, subnets, IAM roles, VPC endpoints, and S3 lifecycle scripts to identify configuration issues. It then provides detailed remediation steps and suggested commands to fix CloudFormation errors.

What tools do I need to troubleshoot EKS access and node replacement issues on a SageMaker HyperPod cluster?

Troubleshooting EKS access and node replacement on SageMaker HyperPod clusters requires aws, jq, python3, bash, kubectl, and session-manager-plugin. These dependencies enable automated diagnostics, EFA health checks, and direct remediation of access problems.

Can I validate VPC endpoints and IAM roles before creating a HyperPod cluster?

Yes, you can validate VPC endpoints and IAM roles before creating a HyperPod cluster. The Skill performs pre-flight validation checks on security group configurations, subnet assignments, and S3 lifecycle scripts to prevent creation failures.

Why does my HyperPod cluster lifecycle script fail during node setup?

HyperPod cluster lifecycle scripts fail during node setup due to misconfigured S3 paths or IAM permissions. The diagnostic tool validates S3 lifecycle scripts and IAM roles, then outputs automated remediation steps to resolve the failures.

What is the best way to fix EFA health check failures on Slurm orchestrated HyperPod clusters?

Fix EFA health check failures on Slurm orchestrated HyperPod clusters by running the diagnostic script with the cluster name and region. It identifies EFA issues and provides specific suggested commands to automate remediation.

Does this diagnostic tool work with both EKS and Slurm orchestration for SageMaker HyperPod?

Yes, this diagnostic tool works with both EKS and Slurm orchestration for SageMaker HyperPod clusters. It diagnoses access issues, node replacement challenges, and configuration errors across both orchestration environments.