---
name: HyperPod Issue Report
slug: hyperpod-issue-report
category: DevOps
description: HyperPod Issue Report collects diagnostic logs and configuration from HyperPod EKS or Slurm clusters and stores them in S3. Use it to troubleshoot node failures, capture cluster state, or prepare AWS Support cases.
github: "https://github.com/awslabs/agent-plugins/tree/main/plugins/sagemaker-ai/skills/hyperpod-issue-report"
language: Python
stars: 867
forks: 145
install: "npx degit https://github.com/awslabs/agent-plugins/tree/main/plugins/sagemaker-ai/skills/hyperpod-issue-report ~/.claude/skills/hyperpod-issue-report"
installs_to: ~/.claude/skills/hyperpod-issue-report
source_path: plugins/sagemaker-ai/skills/hyperpod-issue-report/SKILL.md
collection_size: 25
category_size: 798
collection_url: "https://dirskills.com/collections/awslabs/agent-plugins"
added: 2026-08-22T05:21:37.590Z
last_synced: 2026-08-22T05:21:37.590Z
canonical_url: "https://dirskills.com/skills/hyperpod-issue-report"
---

# HyperPod Issue Report

HyperPod Issue Report collects diagnostic logs and configuration from HyperPod EKS or Slurm clusters and stores them in S3. Use it to troubleshoot node failures, capture cluster state, or prepare AWS Support cases.

**Install:**

```bash
npx degit https://github.com/awslabs/agent-plugins/tree/main/plugins/sagemaker-ai/skills/hyperpod-issue-report ~/.claude/skills/hyperpod-issue-report
```

## README

# 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:DescribeCluster`
- Python 3.8+ and [uv](https://docs.astral.sh/uv/) (see [uv installation docs](https://docs.astral.sh/uv/getting-started/installation/) for install options)
- SSM Agent running on target nodes; node IAM roles need `s3:GetObject`/`s3:PutObject` on the report bucket
- For 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

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

```bash
aws s3 mb s3://<bucket-name> --region <region>
```

**For EKS clusters** (check `Orchestrator.Eks` in describe-cluster output):

1. Ensure kubectl is installed (`which kubectl`). If missing, install it for the current platform.
2. Configure kubeconfig using the EKS cluster name from the describe-cluster response:

   ```bash
   aws eks update-kubeconfig --name <eks-cluster-name> --region <region>
   ```

### 3. Run the Collection Script

```bash
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](references/collection-details.md) for what's in each file)
- Prepare a summary for AWS Support

## Troubleshooting

See [references/troubleshooting.md](references/troubleshooting.md) for error handling, large cluster tuning, and known limitations.