# K8S Debug Gpu Pod

Use when pods are stuck in Pending, CrashLoopBackOff, or ImagePullBackOff state.

- Repository: https://github.com/Project-HAMi/HAMi (5076 stars)
- Category: Media
- License: Apache-2.0
- Last updated: 2026-10-31
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add Project-HAMi/HAMi --skill k8s-debug-gpu-pod -g -a claude-code -y`
Codex: `npx skills add Project-HAMi/HAMi --skill k8s-debug-gpu-pod -g -a codex -y`
Cursor: `npx skills add Project-HAMi/HAMi --skill k8s-debug-gpu-pod -g -a cursor -y`
Gemini CLI: `npx skills add Project-HAMi/HAMi --skill k8s-debug-gpu-pod -g -a gemini-cli -y`

## Description

Use when pods are stuck in Pending, CrashLoopBackOff, or ImagePullBackOff state. Performs event-driven triage to quickly identify root cause, then deep-dives into scheduling failures, resource exhaustion, image pull errors, and crash loops.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

## Interaction

Collect the following from the user **in a single exchange** before starting diagnosis:

| Input | Required | Default |
|-------|----------|---------|
| Namespace | Yes |, |
| Kubeconfig file path | No | `~/.kube/config` |
| Context name | No | current-context in the kubeconfig |

If the user provides a cluster name instead of a context, fuzzy-match it against available contexts in the kubeconfig and confirm the match.

The skill automatically discovers and diagnoses **all unhealthy pods** (Pending, CrashLoopBackOff, ImagePullBackOff, Error) in the namespace. No pod name is needed.

## Command Convention

All `kubectl` commands use shorthand below. **Actual execution must always include explicit flags:**

```bash
kubectl --kubeconfig=<kubeconfig> --context=<context> ...
```

Never rely on default kubeconfig or current-context.

## Diagnostic Workflow

### Step 1: Global Pod Overview

Get a full picture of all pod states in one command:

```bash
kubectl get pods -n <namespace> -o wide
```

Categorize pods into:
- ✅ Running/Completed, healthy, skip
- 🟡 Pending, go to Step 3
- 🔴 CrashLoopBackOff/Error, go to Step 4
- 🔴 ImagePullBackOff/ErrImagePull, go to Step 5
- ⚠️ Other abnormal states, note for report

All unhealthy pods are diagnosed. No manual pod selection needed.

### Step 2: Event Triage

Quick scan of recent warning events for immediate signal:

```bash
kubectl get events -n <namespace> --field-selector type=Warning --sort-by=.lastTimestamp | tail -50
```

Use events to guide which deep-dive steps are most relevant. Common event→action mapping:

The rest: https://github.com/Project-HAMi/HAMi/blob/HEAD/skill/k8s-debug-gpu-pod/SKILL.md