Kubernetes Tutorial · Workloads · Lesson 8 of 26

Rolling Updates and Rollbacks

Ship a new version gradually, watch it, and roll back with one command.

Create a free account to save this page, take notes and track your progress. Sign in

Rolling updates

Changing the pod template (for example the image) starts a rollout: a new ReplicaSet scales up while the old one scales down, controlled by maxSurge (extra pods allowed) and maxUnavailable (pods allowed to be down). Readiness probes decide when a new pod counts as available.

kubectl set image deployment/web web=nginx:1.29-alpine   # or edit the YAML and apply
kubectl rollout status deployment/web
kubectl rollout history deployment/web
kubectl rollout undo deployment/web                       # back to the previous revision

A rollout that can't progress (image doesn't exist, pods crash) stops with the old pods still serving; set progressDeadlineSeconds and alert on it.

A bad image, a stuck rollout and an undo

kubectl create namespace demo-rollout > /dev/null
trap 'kubectl delete namespace demo-rollout --wait=false > /dev/null' EXIT
img() { kubectl -n demo-rollout get deployment web -o jsonpath='{.spec.template.spec.containers[0].image}'; }
kubectl -n demo-rollout create deployment web --image=busybox:1.37 --replicas=2 -- sleep 3600 > /dev/null
kubectl -n demo-rollout rollout status deployment/web --timeout=120s > /dev/null
kubectl -n demo-rollout set image deployment/web busybox=busybox:does-not-exist > /dev/null
kubectl -n demo-rollout rollout status deployment/web --timeout=20s > /dev/null 2>&1 || echo "rollout to $(img) is stuck"
echo "pods still serving the old version: $(kubectl -n demo-rollout get pods -l app=web --field-selector=status.phase=Running -o name | wc -l)"
kubectl -n demo-rollout rollout undo deployment/web > /dev/null
kubectl -n demo-rollout rollout status deployment/web --timeout=120s > /dev/null
echo "after rollout undo: $(img), revisions: $(kubectl -n demo-rollout rollout history deployment/web | grep -cE '^[0-9]')"

kubectl create namespace demo-rollout > /dev/null
trap 'kubectl delete namespace demo-rollout --wait=false > /dev/null' EXIT
img() { kubectl -n demo-rollout get deployment web -o jsonpath='{.spec.template.spec.containers[0].image}'; }
kubectl -n demo-rollout create deployment web --image=busybox:1.37 --replicas=2 -- sleep 3600 > /dev/null
kubectl -n demo-rollout rollout status deployment/web --timeout=120s > /dev/null
kubectl -n demo-rollout set image deployment/web busybox=busybox:does-not-exist > /dev/null
kubectl -n demo-rollout rollout status deployment/web --timeout=20s > /dev/null 2>&1 || echo "rollout to $(img) is stuck"
echo "pods still serving the old version: $(kubectl -n demo-rollout get pods -l app=web --field-selector=status.phase=Running -o name | wc -l)"
kubectl -n demo-rollout rollout undo deployment/web > /dev/null
kubectl -n demo-rollout rollout status deployment/web --timeout=120s > /dev/null
echo "after rollout undo: $(img), revisions: $(kubectl -n demo-rollout rollout history deployment/web | grep -cE '^[0-9]')"

Output

rollout to busybox:does-not-exist is stuck
pods still serving the old version: 2
after rollout undo: busybox:1.37, revisions: 2

Run this on your computer — see “Get Started” for setup.

See Updating a Deployment.

Test yourself

A new image tag doesn't exist. What happens to a rolling update?

All pods go down
New pods fail to pull, the rollout stalls, and old pods keep serving
Kubernetes picks latest instead
The Deployment is deleted

Show answer

Answer: New pods fail to pull, the rollout stalls, and old pods keep serving

maxUnavailable keeps enough old pods running until new ones become ready.

Was this page helpful?