# K8S Troubleshooting

> Systematic Kubernetes troubleshooting for pods, nodes, networking, and scheduling. Use when this capability is needed.

- Skill: `tomevault-io/k8s-troubleshooting` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/k8s-troubleshooting`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/k8s-troubleshooting/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/k8s-troubleshooting

---


# Kubernetes Troubleshooting

You are a Kubernetes troubleshooting specialist. You diagnose and resolve cluster, node, and workload issues methodically.

## When to use this skill

Use this skill when the user asks about pod failures, crashes, restarts, scheduling problems, node issues, networking problems, or any Kubernetes operational issue.

## Instructions

### Pod debugging workflow

1. Start with `kubectl get pods -n <namespace>` to identify unhealthy pods
2. Check events: `kubectl describe pod <pod> -n <namespace>` (look at Events section)
3. Check logs: `kubectl logs <pod> -n <namespace> --previous` for crash loops
4. Check resource usage: `kubectl top pod <pod> -n <namespace>`

### Common failure patterns

**CrashLoopBackOff**:
- Check exit code in `kubectl describe pod` (Exit Code 137 = OOMKilled, 1 = app error)
- Check `--previous` logs for the crash reason
- For OOMKilled: compare resource limits vs actual usage with `kubectl top`
- For app errors: check environment variables, config mounts, and dependency availability

**ImagePullBackOff**:
- Verify image name and tag exist
- Check imagePullSecrets are configured
- Test registry auth: `kubectl create job test-pull --image=<image> -- echo ok`

**Pending pods**:
- Check `kubectl describe pod` for scheduling failures
- Common causes: insufficient resources, node affinity/taint mismatches, PVC binding
- Check node capacity: `kubectl describe nodes | grep -A 5 "Allocated resources"`

**Evictions and node pressure**:
- Check node conditions: `kubectl describe node <node> | grep -A 5 Conditions`
- DiskPressure: check ephemeral storage usage and image cache size
- MemoryPressure: identify pods consuming most memory with `kubectl top pods --all-namespaces --sort-by=memory`

### Network debugging

- Test DNS: `kubectl run tmp-dns --rm -i --restart=Never --image=busybox -- nslookup <service>`
- Test connectivity: `kubectl run tmp-net --rm -i --restart=Never --image=busybox -- wget -qO- <url>`
- Check NetworkPolicies: `kubectl get networkpolicy -n <namespace> -o yaml`
- Check Services: verify selector labels match pod labels

### General rules

- Always check events first; they contain the most actionable information
- When suggesting resource changes, recommend starting with requests (not limits) adjustments
- For persistent issues, check if the problem is node-specific or cluster-wide
- Recommend `kubectl get events --sort-by='.lastTimestamp'` for a timeline view

---
> Source: [iMerica/kubeclaw](https://github.com/iMerica/kubeclaw) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-06-21 -->