debug-kubernetes_skill

This skill helps you diagnose Kubernetes issues with a structured four-phase approach, kubectl commands, and ephemeral debugging to resolve pods and services.

6

GitHub Stars

1

Bundled Files

2 months ago

Catalog Refreshed

4 months ago

First Indexed

Readme & install

Copy the install command, review bundled files from the catalogue, and read any extended description pulled from the listing source.

Installation

Preview and clipboard use veilstrat where the catalogue uses aiagentskills.

npx veilstrat add skill snakeo/claude-debug-and-refactor-skills-plugin --skill debug-kubernetes

SKILL.md13.7 KB

Overview

This skill systematically debugs Kubernetes clusters and workloads using a four-phase methodology: gather information, check logs and metrics, perform interactive investigation, and validate fixes. It focuses on common failure modes like CrashLoopBackOff, ImagePullBackOff, OOMKilled, pending pods, service connectivity, PVC binding failures, and RBAC errors. The goal is fast, repeatable diagnosis with kubectl one-liners, ephemeral debug containers, and actionable remediation steps.

How this skill works

The skill inspects resource state, events, logs, and metrics across namespaces to locate the root cause. It provides targeted kubectl commands for describing resources, tailing logs (including previous instances), viewing top metrics, and launching ephemeral debug containers. Network and storage checks use specialized debug images and commands to verify DNS, connectivity, mounts, and provisioner behavior. Finally it guides applying fixes and validating changes with watches and log verification.

When to use it

Pod repeatedly restarts or is in CrashLoopBackOff
Pod cannot pull image or shows ImagePullBackOff
Pod stays Pending or cannot be scheduled
Container exits with OOMKilled (exit 137)
Service is unreachable from inside or outside the cluster
PersistentVolumeClaim remains unbound or RBAC denies API access

Best practices

Start with kubectl get and kubectl get events to avoid assumptions
Use kubectl describe to surface recent events and failure reasons
Tail logs and use --previous for crashed containers before changing manifests
Use kubectl debug or ephemeral containers for in-cluster troubleshooting
Set resource requests/limits and configure probes to reduce common failures
Label resources and use namespaces to scope and speed diagnosis

Example use cases

Investigate CrashLoopBackOff by checking describe, logs, and adjusting probe timing or resources
Resolve ImagePullBackOff by verifying image name, tags, and imagePullSecrets, or testing docker pull from a node
Debug service reachability by checking service endpoints, running a netshoot/curl pod, and inspecting NetworkPolicy
Fix Pending pods by examining node capacity, affinity/taints, and PVC status
Diagnose PVC binding by describing PVC/PV, checking StorageClass and provisioner events

FAQ

Start with kubectl get pods,svc,deploy -n <namespace> and kubectl get events -n <namespace> --sort-by='.lastTimestamp' to surface immediate clues.

How do I inspect a crashed container’s last logs?

Use kubectl logs <pod> -n <ns> --previous and kubectl describe pod <pod> -n <ns> to see termination reason and events.

When should I use kubectl debug?

Use kubectl debug or ephemeral containers when logs aren’t enough and you need an interactive shell, networking tools, or to replicate the runtime environment without changing the original pod.