Hyperpod Issue Report
AWS LabsOfficialPublished by AWS Labs
- Skill
- Workflow
- Cloud and DevOps
- Apache-2.0
- Low risk
- Has scripts
AutoGineer summary
Written by AutoGineer from the skill’s own files, not by the author
The HyperPod Issue Report skill provides a structured workflow to gather comprehensive diagnostic data from EKS and Slurm-based HyperPod clusters. It utilizes SSM to collect system logs, GPU status, and configuration files from cluster nodes in parallel, storing the results in an S3 bucket. The tool automatically detects the cluster type and supports targeted collection by instance group or specific node IDs, facilitating efficient troubleshooting and preparation for AWS Support cases.
What it does
- Collects diagnostic logs and system configurations from HyperPod nodes via SSM.
- Supports both EKS and Slurm cluster architectures with automatic detection.
- Aggregates cluster-wide resource information and node-specific logs into S3.
- Generates a summary report of collection success and failure statistics.
- Provides EKS-specific cluster resource snapshots using kubectl.
- Offers options to tune performance for large clusters by adjusting worker concurrency.
When to use it
- When investigating node failures or performance degradation in a HyperPod cluster.
- When preparing diagnostic data for an AWS Support case.
- When you need to document the current state of a cluster for auditing or troubleshooting.
- When you need to collect logs from multiple nodes simultaneously to identify patterns.
Advantages
- Reduces manual effort by automating log collection across large clusters.
- Ensures consistent diagnostic data capture for both EKS and Slurm environments.
- Provides configurable parallel execution to handle clusters of varying sizes.
- Centralizes diagnostic artifacts in S3 for easy sharing and analysis.
Usage examples
- “Generate an issue report for my HyperPod cluster named my-cluster in us-west-2 and save it to s3://my-diagnostic-bucket/reports.”
- The agent will verify the cluster, ensure the S3 bucket exists, and run the collection script to gather logs from all nodes, outputting a summary and the S3 path.
- “Collect diagnostics only for the worker-group instance group in my cluster.”
- The agent will execute the collection script with the --instance-groups flag, limiting the diagnostic gathering to nodes within that specific group.
Install
Download the skill as a ZIP:
https://mp-staging.autogineer.com/agent-skills/awslabs/hyperpod-issue-report/downloadUnzip it into the cross-client skills folder of your project:
mkdir -p .agents/skills && unzip hyperpod-issue-report.zip -d .agents/skills
Documentation by AWS Labs
HyperPod Issue Report
Collect diagnostic logs from HyperPod cluster nodes via SSM, store results in S3. Supports both EKS and Slurm clusters with auto-detection. Uses the bundled scripts/hyperpod_issue_report.py for reliable parallel collection.
Prerequisites
AWS CLI configured with permissions:
sagemaker:DescribeCluster,sagemaker:ListClusterNodes,ssm:StartSession,s3:PutObject,s3:GetObject,eks:DescribeClusterPython 3.8+ and uv (see uv installation docs for install options)
SSM Agent running on target nodes; node IAM roles need
s3:GetObject/s3:PutObjecton the report bucketFor EKS clusters: kubectl installed and configured (see Workflow step 2)
Workflow
1. Gather Information
Collect from the user:
Cluster identifier (required): accepts cluster name or full cluster ARN (e.g.,
arn:aws:sagemaker:us-west-2:123456789012:cluster/abc123)AWS region (required unless extractable from ARN)
S3 path for report storage (required, e.g.
s3://bucket/prefix). If the user doesn't have a bucket, create one (e.g.,s3://hyperpod-diagnostics-<account-id>-<region>)Issue description (optional)
Target scope: all nodes, specific instance groups, or specific node IDs (optional)
2. Verify Environment
aws sts get-caller-identity
aws sagemaker describe-cluster --cluster-name <name-or-arn> --region <region>If the S3 bucket doesn't exist, create it:
aws s3 mb s3://<bucket-name> --region <region>For EKS clusters (check Orchestrator.Eks in describe-cluster output):
Ensure kubectl is installed (
which kubectl). If missing, install it for the current platform.Configure kubeconfig using the EKS cluster name from the describe-cluster response:
aws eks update-kubeconfig --name <eks-cluster-name> --region <region>
3. Run the Collection Script
uv run scripts/hyperpod_issue_report.py \
--cluster <cluster-name-or-arn> \
--region <region> \
--s3-path s3://<bucket>[/prefix]Use --help for all options including --instance-groups, --nodes, --max-workers, and --debug. Note: --instance-groups and --nodes are mutually exclusive. Node identifiers accept instance IDs (i-*), EKS names (hyperpod-i-*), or Slurm names (ip-*).
4. Present Results
After collection, the script shows statistics and offers interactive download. Report the S3 location and offer to:
Download the report locally
Help analyze collected diagnostics (see references/collection-details.md for what's in each file)
Prepare a summary for AWS Support
Troubleshooting
See references/troubleshooting.md for error handling, large cluster tuning, and known limitations.
Files
- ATTRIBUTION.mdAdded by AutoGineer926 B
- LICENSELicence file added by AutoGineer9.9 KiB
- NOTICELicence file added by AutoGineer89 B
- SKILL.md3.5 KiB
- references/collection-details.md3.6 KiB
- references/troubleshooting.md3.5 KiB
- scripts/hyperpod_issue_report.pyScript65.3 KiB
references/collection-details.md
Collection Details
What Gets Collected
Common (Both EKS and Slurm)
nvidia_smi.txt— GPU status, utilization, memory, temperatureresource_config.json— HyperPod resource config from/opt/ml/config/resource_config.jsoncluster_logs/— Contents of/var/log/aws/clusters/systemd_services.txt— All systemd service statusesdisk_usage.txt—dfoutputhostname.txt,instance_group.txt,instance_id.txt,cluster_type.txt,timestamp.txt
EKS-Specific (Per-Node)
containerd_status.txt—systemctl status containerdkubelet_status.txt—systemctl status kubeleteks-log-collector-output.txt— EKS log collector execution logeks-logs/— EKS log collector output subdirectories:cni/— CNI plugin logs and configcontainerd/— Runtime logs, config, version, images, containers, tasks, pluginsdocker/— Docker logs (if present)gpu/— GPU diagnosticsipamd/— AWS VPC CNI IPAMD logskernel/— dmesg output, uname infokubelet/— Kubelet logs and configmodinfo/— Kernel module info (lustre, ip_vs, etc.)networking/— Network config, iptables, routes, interfacesnodeadm/— Node administration logssandbox-image/— Sandbox image infostorage/— Mounts, inodes, lsblk, LVM, fstab, XFS, pod local storagesysctls/— Kernel parameterssystem/— Services, systemd-analyze, top, ps, netstat, CPU/IO throttlingvar_log/— System logs from /var/log
EKS-Specific (kubectl — Collected Locally)
Packaged as kubectl_resources.tar.gz, collected from the local machine (not from nodes).
High Priority:
nodes_describe.txt— Detailed node descriptions (capacity, conditions, running pods)pods_all_namespaces.txt/pods_describe_all_namespaces.txt— All pods with detailsevents_all_namespaces.txt— Cluster events sorted by timestamppvcs_all_namespaces.txt/pvcs_describe_all_namespaces.txt— PersistentVolumeClaimsservices_all_namespaces.txt/services_describe_all_namespaces.txt— Network endpoints
Medium Priority:
deployments_all_namespaces.txt,statefulsets_all_namespaces.txt,daemonsets_all_namespaces.txtconfigmaps_all_namespaces.txt,secrets_all_namespaces.txt(metadata only)resourcequotas_all_namespaces.txt,networkpolicies_all_namespaces.txt
Slurm-Specific
sinfo.txt— Node and partition informationsinfo_R.txt— Reasons for node down/drain statesslurmctld_status.txt— Slurm controller daemon statusslurmd_status.txt— Slurm compute node daemon statusopt_slurm_etc/— Slurm configuration from/opt/slurm/etc/nvidia-bug-report.log.gz— NVIDIA bug report (compressed)syslog,kern.log— System logsdmesg_T.txt— Kernel ring buffer with timestampsvar_log_slurm/— Slurm logs from/var/log/slurm/
Report Output Structure
s3://bucket/prefix/cluster-name/YYYYMMDD_HHMMSS/
├── collector_script.sh
├── summary.json
├── kubectl_resources.tar.gz # EKS only
└── instances/
├── worker1_i-abc123.tar.gz
└── worker2_i-abc124.tar.gzTarball filename format: {instance-group}_{instance-id}.tar.gz
Summary JSON Format
{
"cluster_name": "my-cluster",
"cluster_id": "abc123",
"report_id": "20260126_143022",
"timestamp": "2026-01-26T14:30:22.123456",
"total_nodes": 8,
"successful": 7,
"failed": 1,
"results": [
{
"InstanceId": "i-0123456789abcdef0",
"NodeGroup": "worker-group",
"Success": true,
"Output": "...",
"ElapsedTime": 45.2
}
]
}Requirements and compatibility
Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta
“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.
Needs: Needs a command-line tool, Needs Python, Needs Node.js
Security
What our scanner noticed· Low risk
- Scripts that your agent may run
This skill includes scripts that your agent may run. Read them before you use it.
A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.
Attribution and licence
- Published by
- AWS Labs
- Publisher
- AWS Labs (Official)
- Source
- awslabs/agent-plugins · plugins/sagemaker-ai/skills/hyperpod-issue-report · commit fbefb37
- Licence
- Apache License 2.0 (redistribution allowed)
- LICENSE (added by AutoGineer from LICENSE)
- NOTICE (added by AutoGineer from NOTICE)
- ATTRIBUTION.md (written by AutoGineer)
- Synced
AutoGineer is not affiliated with or endorsed by AWS Labs.
Download ZIP
The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download hyperpod-issue-report.zip