Rollouts and debugging
Update a Deployment without downtime, undo it in one command, and work through a broken pod methodically.
Rollouts
Updating a Deployment's pod template starts a rolling update. Kubernetes brings new pods up and old ones down according to maxSurge and maxUnavailable, keeping the desired number of replicas serving throughout.
kubectl set image deployment/web web=nginx:1.28-alpine
kubectl rollout status deployment/web # blocks until finished
kubectl rollout history deployment/web
kubectl rollout undo deployment/web # back to the previous revision
kubectl rollout undo deployment/web --to-revision=3
kubectl rollout restart deployment/web # restart pods without changing the spec| Setting | Effect |
|---|---|
maxUnavailable: 0 | No capacity dip, but the update then needs room for a surge pod |
maxSurge: 1 | One extra pod at a time, the usual safe default |
minReadySeconds | Require a pod to stay ready before it counts as available |
progressDeadlineSeconds | How long a stalled rollout may sit before it is reported as failed |
revisionHistoryLimit | How many old ReplicaSets are kept for undo |
Debugging a failing pod
kubectl get pods -w
kubectl describe pod web-7d9c8b6f4-abcde # events are at the bottom
kubectl logs web-7d9c8b6f4-abcde
kubectl logs web-7d9c8b6f4-abcde --previous # the container that crashed
kubectl exec -it web-7d9c8b6f4-abcde -- sh
kubectl get events --sort-by=.lastTimestamp- Read the status first.
Pending,ImagePullBackOff,CrashLoopBackOffandRunningeach point at a different layer of the problem. - Read the Events section of
describe. It names the failing probe, the missing secret or the reason the pod is unschedulable. - Get logs from the crashed container with
--previous, because a restart wipes the current log. - Diff a broken pod against a working one (
kubectl get deploy web -o yaml). Labels, environment and image tags are the usual culprits.
A field guide to common failures
| Symptom | Usual cause |
|---|---|
Pending | No node has the requested CPU or memory, or a taint has no toleration |
ImagePullBackOff | Wrong image name or tag, or the registry needs an image pull secret |
CrashLoopBackOff | The process exits at once: bad config, missing variable, failing liveness probe |
OOMKilled | The memory limit is below what the application actually needs |
| Service has no endpoints | The selector does not match pod labels, or readiness never passes |
Evicted | Node under pressure; the pod exceeded its memory request |
💡
Set a memory
request and limit on every container. Without a request the scheduler is guessing, and without a limit one runaway pod can take the whole node down with it.FAQ
How do I test a config change without breaking everything?
Watch the update with
kubectl rollout status and revert with kubectl rollout undo. For bigger changes, deploy a second Deployment and shift the Service selector, or use weighted routing at the Ingress.kubectl exec fails with 'container not found'?
The container is restarting or the pod is not running. Check
kubectl get pods and read kubectl logs --previous first, since an interactive shell needs a live container.Related
Pods, Deployments and Services ConfigMaps, Secrets and probes
Last refreshed 2026-09-18.