Rolling updates and rollbacks

Deploying safely and rolling back quickly is the main daily job Kubernetes does for you.

When a Deployment's pod template changes, the controller performs a rollout: it scales the new ReplicaSet up and the old one down step by step.

spec.strategy controls it:

RollingUpdate (default) with maxSurge (extra pods allowed above replicas, default 25%) and maxUnavailable (pods allowed below, default 25%). maxSurge: 1, maxUnavailable: 0 never drops capacity.
Recreate: kill all old pods first, then start new ones. Use when two versions must never run together.

Old pods are removed only as new ones become ready, so a readiness probe is what makes a rollout safe. minReadySeconds adds a wait after ready, and progressDeadlineSeconds marks the rollout as failed if it stalls (it does not roll back automatically).

Commands:

kubectl rollout status deploy/web waits and exits non-zero on failure, ideal in CI.
kubectl rollout history deploy/web lists revisions (old ReplicaSets, up to revisionHistoryLimit).
kubectl rollout undo deploy/web [--to-revision=3] goes back.
kubectl rollout restart deploy/web recreates pods with the same spec.
kubectl rollout pause/resume batches several changes.

Remember that undo changes the live object; if your git manifests still say the bad version, the next apply reintroduces it.

Example

apiVersion: apps/v1
kind: Deployment
metadata: {name: web}
spec:
  replicas: 4
  revisionHistoryLimit: 5
  strategy:
    type: RollingUpdate
    rollingUpdate: {maxSurge: 1, maxUnavailable: 0}
  selector: {matchLabels: {app: web}}
  template:
    metadata: {labels: {app: web}}
    spec:
      containers:
        - name: web
          image: ghcr.io/acme/web:1.4.2
          readinessProbe: {httpGet: {path: /healthz, port: 8080}}
# kubectl set image deploy/web web=ghcr.io/acme/web:1.5.0
# kubectl rollout status deploy/web --timeout=5m || kubectl rollout undo deploy/web

Remember

maxSurge/maxUnavailable tune speed versus spare capacity
Readiness gates the rollout; rollout status for CI
rollout undo reverts the live object, not your git

Watch out for

No readiness probe: pods count as ready on start, so a broken version replaces all good pods.

Check yourself

With replicas: 4, maxSurge: 1 and maxUnavailable: 0, how many pods can exist at most during a rollout?

Official docs: kubernetes.io/docs/concepts/workloads/controllers/deployment/#updating-a-deployment

Example

Remember

Watch out for

Check yourself

Builds on

Unlocks