Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Kubernetes Deployments: Rolling Updates, Rollbacks, and maxUnavailable

Surge and unavailability arithmetic, the readiness probe that decides whether a rollout is real, and how revision history limits the rollback you were counting on.

~5 min readKubernetes
#Kubernetes#Deployments#Operations
3D illustration of ReplicaSet pod stacks shifting replicas from an old revision to a new one

Quick Summary

A Deployment manages ReplicaSets, and a ReplicaSet manages Pods. Every change to the pod template creates a new ReplicaSet with a new revision, and the rollout is the process of shifting replicas from the old one to the new one. That indirection is why rollbacks are cheap (kubectl rollout undo re-activates the previous ReplicaSet) and why editing pods directly is pointless (the controller replaces them).

The rolling update is governed by two numbers: maxSurge (how many extra pods above the desired count may exist) and maxUnavailable (how many fewer than desired may be unavailable). Both default to 25%, rounded toward allowing more (surge up, unavailable down), and together they decide the rollout's pace and its capacity dip. minReadySeconds slows the rollout further by requiring new pods to stay ready before they count as available, and progressDeadlineSeconds turns a stalled rollout into a visible condition instead of a silent hang.

kubectl rollout status waits, kubectl rollout history lists revisions, kubectl rollout undo --to-revision goes back, and kubectl rollout restart forces a new revision with the same template. This guide covers the update strategies, the arithmetic of surge and unavailability, revision history and its limit, the conditions that tell you a rollout is stuck, and the deployment habits that make a rollback actually possible.

Basic Syntax & Core Signatures

yaml
apiVersion: apps/v1 kind: Deployment metadata: name: api annotations: kubernetes.io/change-cause: "api 1.4.2: raise pool size" spec: replicas: 6 revisionHistoryLimit: 10 progressDeadlineSeconds: 600 minReadySeconds: 10 strategy: type: RollingUpdate # or Recreate rollingUpdate: maxSurge: 2 # absolute or percentage maxUnavailable: 1 selector: matchLabels: { app: api } template: metadata: labels: { app: api } spec: containers: - name: api image: ghcr.io/acme/api:1.4.2 ports: [{ containerPort: 8080 }] readinessProbe: httpGet: { path: /ready, port: 8080 } periodSeconds: 5
bash
# Rollout control kubectl apply -f api-deployment.yaml kubectl rollout status deployment/api --timeout=300s kubectl rollout history deployment/api kubectl rollout history deployment/api --revision=3 kubectl rollout undo deployment/api # to the previous revision kubectl rollout undo deployment/api --to-revision=2 kubectl rollout pause deployment/api && kubectl rollout resume deployment/api # New revision without a template change kubectl rollout restart deployment/api # Image update (creates a revision) kubectl set image deployment/api api=ghcr.io/acme/api:1.4.3 kubectl annotate deployment/api kubernetes.io/change-cause="api 1.4.3" # Inspect kubectl get deploy,rs,pods -l app=api kubectl describe deployment api | tail -20 kubectl get deployment api -o jsonpath='{.status.conditions[*].type}={.status} '
yaml
# Recreate: all old pods die before any new one starts (downtime, clean state) strategy: type: Recreate

Key Comparison Table

AspectRollingUpdateRecreate
DowntimeNone if capacity allowsFull, for the duration
Extra capacitymaxSurge podsNone
Capacity dipUp to maxUnavailableEverything
Two versions at onceYes (both serve traffic)No
Needs a ready probePractically, yesNo
Use whenDefault for stateless servicesSingleton, schema migration, PVC with RWO
SettingDefaultEffect
maxSurge25%Extra pods created above replicas, rounded up
maxUnavailable25%Pods allowed unavailable, rounded down
minReadySeconds0Time a pod must stay ready to count as available
progressDeadlineSeconds600Time before the rollout is marked failed
revisionHistoryLimit10Old ReplicaSets kept for rollout undo
terminationGracePeriodSeconds30 (pod spec)Time for graceful shutdown during rollout
ConditionTrue means
AvailableAt least replicas - maxUnavailable pods are ready
ProgressingA rollout is advancing, or completed within the deadline
ReplicaFailureThe ReplicaSet cannot create pods (quota, admission)

Practical Edge Cases & Deep Dives

1. The surge and unavailability arithmetic

text
replicas: 10, maxSurge: 25% -> 3 (rounded up), maxUnavailable: 25% -> 2 (rounded down) Maximum pods at any moment: 13 Minimum available during the rollout: 8

Percentages round in the direction that keeps the rollout safe: surge up, unavailability down. Absolute values are clearer for small replica counts — with replicas: 2, a 25% maxUnavailable is 0 (rounded down) and 25% surge is 1 (rounded up), so the rollout runs one pod at a time; with replicas: 1, maxUnavailable: 0 plus maxSurge: 1 is the only combination that avoids downtime. Setting both to 0 is rejected by the API server, because no rollout can proceed.

bash
kubectl get rs -l app=api -o custom-columns=NAME:.metadata.name,DESIRED:.spec.replicas,READY:.status.readyReplicas

Watching the ReplicaSet's desired count climb while the old one falls is the clearest view of the rollout in progress.

2. A rollout that reports success while users see errors

yaml
readinessProbe: httpGet: { path: /healthz, port: 8080 } # returns 200 as soon as the process listens

If the readiness probe passes before the app can serve traffic — DB connection pool not yet built, cache cold, migrations pending — the rollout is "complete" and users get 500s for the length of the warm-up. minReadySeconds does not fix that; only a readiness probe that reflects actual serving ability does. The usual pair is a liveness probe on a cheap always-true endpoint and a readiness probe on a slow, dependency-touching endpoint.

The inverse failure is a probe that never passes, which stalls the rollout at Waiting for deployment "api" rollout to finish: 2 out of 6 new replicas have been updated until progressDeadlineSeconds marks it failed. In both cases, kubectl describe deployment shows the condition and kubectl get pods shows which pods are not ready and why.

3. progressDeadlineSeconds and what "stalled" means

bash
$ kubectl rollout status deployment/api --timeout=120s Waiting for deployment "api" rollout to finish: 3 of 6 updated replicas are available... error: timed out waiting for the condition $ kubectl describe deployment api | grep -A3 Conditions Progressing False ProgressDeadlineExceeded

The deadline is measured from the last progress (not from the start), so a slow but advancing rollout is not failed. When it trips, the Deployment keeps the new ReplicaSet at its current size and leaves the old pods running — the rollout is paused, not reverted. The next kubectl rollout undo returns to the previous revision; the alternative is to fix the template and apply again, which creates another revision.

4. Revision history, change-cause, and the rollback that is not possible

bash
$ kubectl rollout history deployment/api deployment.apps/api REVISION CHANGE-CAUSE 7 api 1.4.0: raise pool size 8 api 1.4.1: add /ready 9 <none>

Revisions exist for pod-template changes; kubectl set image, apply with a new image, resource or env edit each create one, while kubectl scale does not. Annotations are only recorded when set (kubernetes.io/change-cause, or the older --record, which is deprecated and noisy in managed fields). revisionHistoryLimit: 10 means revision 0 is pruned beyond that; if the bad change was deployed as revision 1 and 12 more followed, --to-revision=1 is gone and the fix must be a new template. In GitOps setups, history is cosmetic and the real rollback is a revert commit.

bash
kubectl rollout undo deployment/api --to-revision=8 kubectl annotate deployment/api kubernetes.io/change-cause="rollback: 1.4.1 was OOMKilled" --overwrite

5. Immutable fields and the apply that fails

bash
$ kubectl apply -f api-deployment.yaml The Deployment "api" is invalid: spec.selector: Invalid value: ...: field is immutable

spec.selector cannot change after creation, because existing ReplicaSets' pods would no longer be adopted. The same applies to a Service's clusterIP and a few others. The options are kubectl replace --force (delete and recreate, with downtime), kubectl delete deployment api && kubectl apply -f ..., or editing the object through GitOps with the intended replacement. A rolling replacement of a Deployment by the same mechanism is what kubectl create --save-config plus apply is for, but nothing avoids the delete for selector changes: plan the label scheme before the first deploy.

6. Scaling, HPA ownership, and the replicas field that fights back

bash
$ kubectl scale deployment/api --replicas=20 $ kubectl get deploy api -o jsonpath='{.spec.replicas} {.status.replicas}' 3 3

If a HorizontalPodAutoscaler targets the Deployment, it owns spec.replicas: a manual scale is reset on the next autoscaler run (up to 15-30 seconds later). The correct approaches are to change minReplicas/maxReplicas on the HPA, or to pause the HPA (delete it) if the manual count is needed. HPA also ignores spec.replicas entirely when computing targets — its currentReplicas comes from the Deployment's status — so a manually scaled-down service is scaled back up as soon as the metric says so.

bash
kubectl get hpa kubectl describe hpa api | grep -E 'Min replicas|Max replicas|Current replicas'

Common Runtime & Configuration Mistakes

SymptomCauseFix
Rollout hangs at Waiting for rollout to finishNew pods never become readydescribe pod; fix the readiness probe or app
ProgressDeadlineExceededNo progress within progressDeadlineSecondsundo, then fix and reapply
Users see errors at rollout time, status says completeReadiness probe too shallowProbe a dependency-touching endpoint
Downtime during rollout with replicas: 1maxUnavailable > 0maxUnavailable: 0, maxSurge: 1
API rejects the strategymaxSurge and maxUnavailable both 0Set one above zero
field is immutable on applyChanged spec.selectorRecreate the Deployment with the intended labels
undo --to-revision says revision not foundPruned by revisionHistoryLimitRaise the limit; roll forward instead
History shows <none> for change causeAnnotation not setSet kubernetes.io/change-cause per deploy
Old ReplicaSets pile upHigh revisionHistoryLimitLower it; each RS holds pod templates only
Manual scale has no effectHPA owns replicasChange HPA bounds
Pods killed before finishing requeststerminationGracePeriodSeconds too shortRaise it; drain on SIGTERM
Two versions serving different behaviourExpected during RollingUpdateKeep the API backward-compatible across versions

Deployments are a small state machine over ReplicaSets, and nearly every rollout incident is one of three things: a readiness probe that lies about health, a capacity setting that cannot cover the update, or a rollback that is impossible because the revision is gone. Fixing the probe, sizing maxSurge/maxUnavailable for the smallest replica count in use, and keeping the last ten revisions with change causes turns a risky deploy into a reversible one.

Try matching browser tools

All tools

Small utilities that fit Kubernetes work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Kubernetes guides

More in Kubernetes

All Kubernetes guides

The guides filed next to this one in Kubernetes, in library order.