k8s-debuglisted
Install: claude install-skill polytheseus/sre-skills
# Kubernetes debugging
Work from the outside in: **workload → pod → container → node → network**.
At each layer, read the status and events before forming a theory.
## Ground rules
- Use read-only commands (`get`, `describe`, `logs`, `top`, `events`,
`auth can-i`) freely. Before anything that changes the cluster (`delete`,
`rollout restart`, `scale`, `edit`, `apply`, `cordon`/`drain`), show the
command and its effect, and get the user's go-ahead.
- Confirm the context and namespace first. Debugging the wrong cluster is a
classic way to lose an hour or to break something else:
```bash
kubectl config current-context
kubectl get ns
```
- Always pass `-n <ns>` explicitly instead of relying on the default namespace.
## 1. Workload overview
```bash
kubectl get deploy,sts,ds,rs,pods -n <ns> -o wide
kubectl describe deploy/<name> -n <ns> # conditions, replica counts, events
kubectl rollout status deploy/<name> -n <ns> --timeout=10s
kubectl get events -n <ns> --sort-by=.lastTimestamp | tail -30
```
If `READY` is lower than desired, take one failing pod and go to step 2.
If the rollout is stuck, compare the new and old ReplicaSets: the new one is
usually failing for one of the reasons below.
## 2. Pod status → cause
Run `kubectl describe pod/<pod> -n <ns>` and read **Events** at the bottom,
plus `State` / `Last State` / `Reason` / `Exit Code` per container.
| Symptom | Likely causes | Check |
|---|---|---|
| `Pending` | Insufficient CPU/memory, unsatisfiab