kubectl-debugging
Debug K8s pods/nodes with kubectl debug — ephemeral containers, pod copying, debug profiles, interactive sessions. Use when the user mentions kubectl debug or debugging pods.
- Installs
- 90
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/laurigates/claude-plugins --skill kubectl-debugging- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads kubectl-debugging automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
kubectl debug - Interactive Kubernetes Debugging
Expert knowledge for debugging Kubernetes resources using kubectl debug - ephemeral containers, pod copies, and node access.
When to Use This Skill
| Use this skill when... | Use <sibling> instead when... |
|---|---|
Attaching an ephemeral debug container to a running pod with kubectl debug | Use kubernetes-operations for general kubectl workflows (apply, get, describe, logs) |
| Creating a pod copy with a different image or command for interactive troubleshooting | Use helm-debugging when the failure is in template rendering or chart configuration, not the running container |
| Opening a node-level debug session to inspect host namespaces or filesystems | Use helm-release-recovery when the recovery action is a Helm rollback rather than per-pod debugging |
Core Capabilities
kubectl debug automates common debugging tasks:
- Ephemeral Containers: Add debug containers to running pods without restart
- Pod Copying: Create modified copies for debugging (different images, commands)
- Node Debugging: Access node host namespaces and filesystem
Context Safety (CRITICAL)
Always specify --context explicitly in every kubectl command:
# CORRECT: Explicit context
kubectl --context=prod-cluster debug mypod -it --image=busybox
# WRONG: Relying on current context
kubectl debug mypod -it --image=busybox # Which cluster?
Quick Reference
Add Ephemeral Debug Container
# Interactive debugging with busybox
kubectl --context=my-context debug mypod -it --image=busybox
# Target specific container's process namespace
kubectl --context=my-context debug mypod -it --image=busybox --target=mycontainer
# Use a specific debug profile
kubectl --context=my-context debug mypod -it --image=busybox --profile=netadmin
Copy Pod for Debugging
# Create debug copy
kubectl --context=my-context debug mypod -it --copy-to=mypod-debug --image=busybox
# Copy and change container image
kubectl --context=my-context debug mypod --copy-to=mypod-debug --set-image=app=busybox
# Copy and modify command
kubectl --context=my-context debug mypod -it --copy-to=mypod-debug --container=myapp -- sh
# Copy on same node
kubectl --context=my-context debug mypod -it --copy-to=mypod-debug --same-node --image=busybox
Debug Node
# Interactive node debugging (host namespaces, filesystem at /host)
kubectl --context=my-context debug node/mynode -it --image=busybox
# With sysadmin profile for full capabilities
kubectl --context=my-context debug node/mynode -it --image=ubuntu --profile=sysadmin
Debug Profiles
| Profile | Use Case | Capabilities |
|---|---|---|
legacy | Default, unrestricted | Full access (backwards compatible) |
general | General purpose | Moderate restrictions |
baseline | Minimal restrictions | Pod security baseline |
netadmin | Network troubleshooting | NET_ADMIN capability |
restricted | High security environments | Strictest restrictions |
sysadmin | System administration | SYS_PTRACE, SYS_ADMIN |
# Network debugging (tcpdump, netstat, ss)
kubectl --context=my-context debug mypod -it --image=nicolaka/netshoot --profile=netadmin
# System debugging (strace, perf)
kubectl --context=my-context debug mypod -it --image=ubuntu --profile=sysadmin
Common Debug Images
| Image | Size | Use Case |
|---|---|---|
busybox | ~1MB | Basic shell, common utilities |
alpine | ~5MB | Shell with apk package manager |
ubuntu | ~77MB | Full Linux with apt |
nicolaka/netshoot | ~350MB | Network debugging (tcpdump, dig, curl, netstat) |
gcr.io/k8s-debug/debug | Varies | Official Kubernetes debug image |
Debugging Patterns
Network Connectivity Issues
# Add netshoot container for network debugging
kubectl --context=my-context debug mypod -it \
--image=nicolaka/netshoot \
--profile=netadmin
# Inside container:
# - tcpdump -i any port 80
# - dig kubernetes.default
# - curl -v http://service:port
# - ss -tlnp
# - netstat -an
Application Crashes
# Copy pod with different entrypoint to inspect
kubectl --context=my-context debug mypod -it \
--copy-to=mypod-debug \
--container=app \
-- sh
# Inside: check filesystem, env vars, config files
Process Inspection
# Target container's process namespace
kubectl --context=my-context debug mypod -it \
--image=busybox \
--target=mycontainer
# Inside: ps aux, /proc inspection
Node-Level Issues
# Debug node with host access
kubectl --context=my-context debug node/worker-1 -it \
--image=ubuntu \
--profile=sysadmin
# Inside:
# - Host filesystem at /host
# - chroot /host for full access
# - journalctl, systemctl, dmesg
Non-Destructive Debugging
# Create copy, keeping original running
kubectl --context=my-context debug mypod -it \
--copy-to=mypod-debug \
--same-node \
--share-processes \
--image=busybox
# Original pod continues serving traffic
# Debug copy shares storage if on same node
Key Options
| Option | Description |
|---|---|
-it | Interactive TTY (required for shell access) |
--image | Debug container image |
--container | Name for the debug container |
--target | Share process namespace with this container |
--copy-to | Create a copy instead of ephemeral container |
--same-node | Schedule copy on same node (with --copy-to) |
--set-image | Change container images in copy |
--profile | Security profile (legacy, netadmin, sysadmin, etc.) |
--share-processes | Enable process namespace sharing (default: true with --copy-to) |
--replace | Delete original pod when creating copy |
Best Practices
- Use appropriate profiles - Match capabilities to debugging needs
- Prefer ephemeral containers - Less disruptive than pod copies
- Use
--copy-tofor invasive debugging - Preserve original pod - Clean up debug pods - Delete copies after debugging
- Use
--same-node- For accessing shared storage/network conditions
Cleanup
# List debug pod copies
kubectl --context=my-context get pods | grep -E "debug|copy"
# Delete debug pods
kubectl --context=my-context delete pod mypod-debug
Requirements
- Kubernetes 1.23+ for ephemeral containers (stable)
- Kubernetes 1.25+ for debug profiles
- RBAC permissions for pods/ephemeralcontainers
For detailed option reference, examples, and troubleshooting patterns, see REFERENCE.md.
FAQ
What does the kubectl-debugging skill do?
Debug K8s pods/nodes with kubectl debug — ephemeral containers, pod copying, debug profiles, interactive sessions. Use when the user mentions kubectl debug or debugging pods.
How do I install kubectl-debugging?
Run npx skills add https://github.com/laurigates/claude-plugins --skill kubectl-debugging in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/kubectl-debugging/ (personal) or .claude/skills/kubectl-debugging/ (project).
Which AI agents can use kubectl-debugging?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is kubectl-debugging safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains kubectl-debugging?
It is published by laurigates in laurigates/claude-plugins. It has 90 recorded installs.
More from laurigates/claude-plugins
python-code-quality
laurigates/claude-plugins
Python code quality with ruff and ty. Use when the user mentions ruff, ty, linting, formatting, type checking, or Python code style.
python-testing
laurigates/claude-plugins
Python testing with pytest, coverage, fixtures, and mocking. Use when the user mentions pytest, unit tests, coverage, fixtures, mocking, or writing Python tests.
pytest-advanced
laurigates/claude-plugins
Advanced pytest: fixtures, markers, parametrization, parallel execution. Use when implementing test infrastructure, writing fixtures, or running with coverage.
basedpyright-type-checking
laurigates/claude-plugins
Open the skill to read its SKILL.md instructions.
Popular code quality & workflow skills
grill-me
mattpocock/skills
A relentless interview to sharpen a plan or design.
improve-codebase-architecture
mattpocock/skills
Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
handoff
mattpocock/skills
Compact the current conversation into a handoff document for another agent to pick up.
domain-modeling
mattpocock/skills
Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a GLOSSARY.md, or recording or editing an ADR.
codebase-design
mattpocock/skills
Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.
diagnosing-bugs
mattpocock/skills
Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.