k8s-debug

Diagnoses Kubernetes GPU workload failures through an ordered kubectl triage workflow.

3|Updated Jul 2, 2026
One-click install
npx skills add https://github.com/ArangoGutierrez/claude-toolkit --skill k8s-debug-arangogutierrez
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: k8s-debug
Source: https://github.com/ArangoGutierrez/claude-toolkit/tree/main/.claude/skills/k8s-debug
Command: npx skills add https://github.com/ArangoGutierrez/claude-toolkit --skill k8s-debug-arangogutierrez

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Debugging failing Kubernetes pods — especially GPU workloads — often turns into random log-diving that misses the real cause. This Skill enforces a fixed triage order (pod status, events, logs, node conditions, resources, GPU state, DRA claims) so root causes like CUDA driver mismatches, missing GPU allocatable, or unallocated ResourceClaims are found before you change code or resource limits. ## Core Features & Use Cases - Ordered triage workflow: Runs pod status, events (before logs), container logs, node conditions, and resource requests in a fixed sequence using kubectl. - GPU-specific diagnostics: Checks GPU allocatable counts, the nvidia-device-plugin DaemonSet, MIG profiles, and CUDA driver/runtime mismatches via a full scheduling checklist. - DRA troubleshooting: Walks ResourceClaim allocation, driver registration via resourceslices, CDI spec generation, and /dev/nvidia* device presence. - Use Case: A training pod is in CrashLoopBackOff with a CUDA error. The Skill checks events and logs, then flags the common pattern — a driver/runtime mismatch rather than an application bug — saving you from rewriting working code. ## Quick Start Ask the AI to run k8s-debug on the pod training-job-7f8 in namespace ml because it is stuck in CrashLoopBackOff.

Frequently Asked Questions about k8s-debug

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

FAQPage Schema
How do I debug a pod stuck in CrashLoopBackOff on Kubernetes?▼

Start with kubectl describe pod and cluster events before reading logs, since events explain why logs may be empty. Then check kubectl logs --previous, node conditions, and allocated resources to find the root cause.

How to troubleshoot a GPU pod stuck in Pending state?▼

Check node GPU allocatable counts, the nvidia-device-plugin DaemonSet health, node selectors and taints, and MIG profile matches. Insufficient allocatable GPU capacity is the most common cause of Pending GPU pods.

Why does my container show CUDA errors in Kubernetes?▼

CUDA errors in containers usually indicate a driver/runtime version mismatch, not an application bug. Verify the nvidia-smi driver version meets the CUDA toolkit requirement before changing application code.

Does this debugging workflow require the NVIDIA GPU Operator?▼

The GPU-specific steps — device plugin checks, MIG profiles, and DRA — assume the NVIDIA GPU Operator is installed. On clusters without GPU nodes, those steps are skipped and only standard pod triage applies.

When should I not use Kubernetes pod triage for debugging?▼

Do not use pod triage for application logic bugs unrelated to scheduling or node resources. For general code-level debugging, a systematic debugging approach for the application itself is more appropriate.