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.

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
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# 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} '# Recreate: all old pods die before any new one starts (downtime, clean state)
strategy:
type: RecreateKey Comparison Table
| Aspect | RollingUpdate | Recreate |
|---|---|---|
| Downtime | None if capacity allows | Full, for the duration |
| Extra capacity | maxSurge pods | None |
| Capacity dip | Up to maxUnavailable | Everything |
| Two versions at once | Yes (both serve traffic) | No |
| Needs a ready probe | Practically, yes | No |
| Use when | Default for stateless services | Singleton, schema migration, PVC with RWO |
| Setting | Default | Effect |
|---|---|---|
maxSurge | 25% | Extra pods created above replicas, rounded up |
maxUnavailable | 25% | Pods allowed unavailable, rounded down |
minReadySeconds | 0 | Time a pod must stay ready to count as available |
progressDeadlineSeconds | 600 | Time before the rollout is marked failed |
revisionHistoryLimit | 10 | Old ReplicaSets kept for rollout undo |
terminationGracePeriodSeconds | 30 (pod spec) | Time for graceful shutdown during rollout |
| Condition | True means |
|---|---|
Available | At least replicas - maxUnavailable pods are ready |
Progressing | A rollout is advancing, or completed within the deadline |
ReplicaFailure | The ReplicaSet cannot create pods (quota, admission) |
Practical Edge Cases & Deep Dives
1. The surge and unavailability arithmetic
replicas: 10, maxSurge: 25% -> 3 (rounded up), maxUnavailable: 25% -> 2 (rounded down)
Maximum pods at any moment: 13
Minimum available during the rollout: 8Percentages 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.
kubectl get rs -l app=api -o custom-columns=NAME:.metadata.name,DESIRED:.spec.replicas,READY:.status.readyReplicasWatching 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
readinessProbe:
httpGet: { path: /healthz, port: 8080 } # returns 200 as soon as the process listensIf 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
$ 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 ProgressDeadlineExceededThe 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
$ 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.
kubectl rollout undo deployment/api --to-revision=8
kubectl annotate deployment/api kubernetes.io/change-cause="rollback: 1.4.1 was OOMKilled" --overwrite5. Immutable fields and the apply that fails
$ kubectl apply -f api-deployment.yaml
The Deployment "api" is invalid: spec.selector: Invalid value: ...: field is immutablespec.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
$ kubectl scale deployment/api --replicas=20
$ kubectl get deploy api -o jsonpath='{.spec.replicas} {.status.replicas}'
3 3If 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.
kubectl get hpa
kubectl describe hpa api | grep -E 'Min replicas|Max replicas|Current replicas'Common Runtime & Configuration Mistakes
| Symptom | Cause | Fix |
|---|---|---|
Rollout hangs at Waiting for rollout to finish | New pods never become ready | describe pod; fix the readiness probe or app |
ProgressDeadlineExceeded | No progress within progressDeadlineSeconds | undo, then fix and reapply |
| Users see errors at rollout time, status says complete | Readiness probe too shallow | Probe a dependency-touching endpoint |
Downtime during rollout with replicas: 1 | maxUnavailable > 0 | maxUnavailable: 0, maxSurge: 1 |
| API rejects the strategy | maxSurge and maxUnavailable both 0 | Set one above zero |
field is immutable on apply | Changed spec.selector | Recreate the Deployment with the intended labels |
undo --to-revision says revision not found | Pruned by revisionHistoryLimit | Raise the limit; roll forward instead |
History shows <none> for change cause | Annotation not set | Set kubernetes.io/change-cause per deploy |
| Old ReplicaSets pile up | High revisionHistoryLimit | Lower it; each RS holds pod templates only |
| Manual scale has no effect | HPA owns replicas | Change HPA bounds |
| Pods killed before finishing requests | terminationGracePeriodSeconds too short | Raise it; drain on SIGTERM |
| Two versions serving different behaviour | Expected during RollingUpdate | Keep 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 toolsSmall utilities that fit Kubernetes work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Kubernetes guides
All Kubernetes guideskubectl Output: jsonpath, custom-columns, and the Debugging Commands Worth Knowing
jsonpath for one value in a script, custom-columns for tables people read, and kubectl debug when the container has no shell. Includes the three quoting layers that break jsonpath.
Kubernetes Namespaces, ResourceQuotas, and LimitRanges
A namespace is only a boundary when quota and limit range make it one. Aggregate caps, per-pod defaults, the admission errors they produce, and namespaces stuck Terminating.
Kubernetes StatefulSets: Ordinal Identities, Headless Services, and PVC Lifecycle
Why each StatefulSet pod keeps a name, a DNS record, and its own PVC; how OrderedReady gates startup on readiness; and how partition-based updates canary a single quorum member.
Kubernetes securityContext, Capabilities, and Pod Security Standards
The five fields that remove most container escapes, which of them only exist at container level, and how the restricted profile enforces the same settings at admission.
More in Kubernetes
All Kubernetes guidesThe guides filed next to this one in Kubernetes, in library order.
- Kubernetes DaemonSets: Node Selectors, Taints, and Rolling Update Strategies
- Kubernetes ConfigMaps and Secrets: envFrom, Volume Mounts, and Immutability
- Horizontal Pod Autoscaler (HPA): Scaling Metrics and Stabilization Windows
- Kubernetes Ingress: Path Types, Controller Annotations, and TLS Termination