k8s-debug

Diagnoses Kubernetes workload failures by collecting structured evidence across pods, networks, nodes, and configurations.

Updated Apr 15, 2026
One-click install
npx skills add https://github.com/ToanPV90/dotfiles --skill k8s-debug-toanpv90
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: k8s-debug
Source: https://github.com/ToanPV90/dotfiles/tree/main/claude/.claude/skills/k8s-debug
Command: npx skills add https://github.com/ToanPV90/dotfiles --skill k8s-debug-toanpv90

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) and references (resource) components.

What problem does it solve?

It helps you rapidly pinpoint the root cause of Kubernetes workload, networking, and storage failures by turning vague symptoms into a structured, evidence-driven troubleshooting path.

Core Features & Use Cases

  • Deterministic debugging workflow: Guides you through preflight, problem-layer identification, diagnostics collection, reference navigation, targeted fixes, and verification.
  • Focused diagnostic scripts for common failure modes: Cluster health snapshots, pod-level diagnostics, and network/DNS investigations with clear output and guardrails.
  • Safety-first handling for disruptive actions: Requires snapshot/rollback planning before destructive or high-impact commands.

Use case: When a deployment starts producing CrashLoopBackOff pods and DNS/service connectivity complaints, run the right pod diagnostics and follow the symptom-mapped reference sections to identify whether the cause is application crashes, image pull/auth issues, resource pressure, DNS/CoreDNS health, network policy blocking, or storage/PVC failures.

Quick Start

Run the pod diagnostics for your failing pod by executing: python3 ./scripts/pod_diagnostics.py <pod-name> -n <namespace>.

Frequently Asked Questions about k8s-debug

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

FAQPage Schema
How do I diagnose CrashLoopBackOff and OOMKilled pods in Kubernetes?

Diagnose CrashLoopBackOff and OOMKilled pods by running a script-driven pod diagnostics workflow that collects structured evidence across application logs, resource limits, and configuration layers to pinpoint the root cause safely.

What is the best way to troubleshoot Kubernetes DNS resolution failures?

Troubleshoot Kubernetes DNS resolution failures by running focused network and DNS diagnostic scripts that inspect CoreDNS health and network policies, mapping vague connectivity complaints into an evidence-driven investigation path.

How do I fix ImagePullBackOff and Pending pod states in kubectl?

Fix ImagePullBackOff and Pending states by identifying the problem layer through preflight checks and targeted kubectl diagnostics, determining whether the failure stems from image authentication, resource pressure, or node scheduling constraints.

Can I use this Skill to investigate stuck Kubernetes rollouts and PVC mount problems?

You can investigate stuck rollouts and PVC mount problems by collecting cluster health snapshots and storage diagnostics, applying safety guardrails that require rollback planning before executing any disruptive kubectl operations.

Do I need special kubectl permissions to troubleshoot Kubernetes workload failures?

You need kubectl access to the active context to troubleshoot Kubernetes workload failures, allowing the diagnostic scripts to gather pod, service, node, and storage layer evidence without requiring elevated cluster-admin privileges.

Why does Kubernetes pod diagnostics require a structured troubleshooting workflow?

Kubernetes pod diagnostics require a structured workflow to prevent destructive actions, ensuring you collect baseline evidence and create snapshot or rollback plans before applying targeted fixes that could impact the active cluster state.