kubectl Debugging Workflows That Actually Matter

Doctrine

Under pressure, operators thrash because they lack a sequence. They run random commands, apply random YAML, and destroy the causal thread.

Kubblai doctrine: evidence first; smallest change; explicit verification; memorialize the lesson.

• Prefer `describe` + events before logs when the failure might be platform-level.
• Treat `rollout status` as a gate; don’t assume progress.
• Use `auth can-i` to prove RBAC instead of arguing about it.

The minimal workflow

A sequence that covers most incidents without expanding blast radius.

kubectl get pods -n <ns> -o wide
kubectl describe pod <pod> -n <ns>
kubectl get events -n <ns> --sort-by=.lastTimestamp | tail -n 40
kubectl logs <pod> -n <ns> --previous --all-containers=true

Rollouts and reversibility

Rollouts are controlled change. Make them explicit.

kubectl rollout status deploy/<name> -n <ns>
kubectl rollout history deploy/<name> -n <ns>
# rollback posture (use deliberately):
kubectl rollout undo deploy/<name> -n <ns>

Targeted YAML inspection

You rarely need the entire object. You need the governing fields: requests, probes, selectors, and references. Extract them and keep the investigation narrow.

kubectl get pod <pod> -n <ns> -o yaml | rg -n "resources:|requests:|limits:|readinessProbe|livenessProbe|startupProbe|envFrom|secretKeyRef|configMapKeyRef"

RBAC proof

When permission is denied, prove it with an exact sentence.

kubectl auth whoami
kubectl auth can-i <verb> <resource> -n <ns>

Field notes

kubectl can become the incident when you list the world during API saturation. Prefer targeted queries. Prefer read-only diagnosis during systemic failure.

When the control plane is unhealthy, reduce churn. ‘Trying harder’ is not a strategy.