Rolling updates and rollback
Follow old and new ReplicaSets under explicit availability and surge limits.
What you will understand
- Explain what triggers a Deployment rollout
- Calculate simple surge and unavailable bounds
- Perform a rollback without assuming data or config is restored
Builds on: Deployments and ReplicaSets
Mental model: two release recipes, one controlled transition
A Deployment rollout starts when its Pod template changes. Updating the container image, an environment value in that template, or template annotations can create a new revision. Changing only spec.replicas scales the workload without creating a new Pod-template revision. Editing a ConfigMap under the same name does not by itself change the Deployment template, so it does not automatically trigger this rollout machinery.
The Deployment controller manages an old and a new ReplicaSet during a rolling update. Each ReplicaSet creates or removes its own Pods according to its current target. The scheduler and kubelets still perform placement and execution. Existing Pods do not swap their process binary in place when an image field changes in the parent. New Pods run the new template while old Pods are terminated according to the update plan.
maxSurge allows temporary extra replicas above the desired count. maxUnavailable bounds how many desired replicas may be unavailable during the transition. With desired three, surge one, and unavailable zero, the controller can normally introduce a fourth non-terminating replica and should keep at least three available before removing another old replica. Terminating Pods and asynchronous observations can cause visible totals or resource usage above a naive desired-plus-surge count. Budget arithmetic is a controller policy, not instantaneous accounting of every process.
Rolling update with a one-Pod surge
Show the Deployment coordinating old and new ReplicaSets under explicit bounds.
Old ReplicaSet A has three available Pods. The changed image yields ReplicaSet B, initially at zero.
- Deployment target: 3 to RS A: 3 availableold template
- Deployment target: 3 to RS B: 0new template
Read the complete visual sequence
- A template update creates a new revision
Old ReplicaSet A has three available Pods. The changed image yields ReplicaSet B, initially at zero.
- Use the surge allowance
The Deployment sets B’s target to one. B’s controller creates that Pod while A retains three available replicas.
- Trade capacity after availability
When B’s Pod becomes available, A can scale down to two. Repeat this controlled exchange until B owns all three desired replicas.
Failure: surge cannot fit
Failure: surge cannot fit
- Old replicas fill usable capacity
Three old Pods are available. A new Pod is created under surge allowance but still needs a feasible node.
- Availability policy prevents a shortcut
With maxUnavailable zero, the controller cannot simply discard an available old replica before a replacement becomes available.
- Resolve capacity or choose policy deliberately
Add suitable capacity, reduce resource demand safely, or review the rollout budget. Do not mistake this protective stall for a container bug.
About this model
Desired replicas are three, maxSurge is one, maxUnavailable is zero. Old replicas stay healthy; unrelated failures and terminating overlap are omitted from counts. The update policy cannot prevent independent application or node failures.
Walkthrough: state the update budget
Use this complete Deployment as rollout-demo.yaml in a disposable namespace. The HTTP probe uses nginx’s existing root page. It demonstrates HTTP availability, not deep business correctness. Resource requests and placement constraints are intentionally deferred to the next level.
apiVersion: apps/v1
kind: Deployment
metadata:
name: rollout-demo
spec:
replicas: 3
minReadySeconds: 5 # Stay ready before counting as available.
progressDeadlineSeconds: 120 # Report a stalled rollout; not auto-rollback.
revisionHistoryLimit: 3
strategy:
type: RollingUpdate
rollingUpdate:
maxSurge: 1
maxUnavailable: 0
selector:
matchLabels:
app: rollout-demo
template:
metadata:
labels:
app: rollout-demo
spec:
containers:
- name: web
image: nginx:1.27.5
readinessProbe:
httpGet:
path: /
port: 80
periodSeconds: 5
kubectl apply -f rollout-demo.yaml
kubectl rollout status deployment/rollout-demo --timeout=180s
kubectl rollout history deployment/rollout-demo
# Inspect a controlled image update in your disposable lab.
kubectl set image deployment/rollout-demo web=nginx:1.28.0
kubectl get rs -l app=rollout-demo -w
The training image versions are examples, not claims that an upgrade is appropriate for your application. For a real release, use verified image identities and compatibility checks. After the image update, inspect both ReplicaSets and Pods. The new replica must become ready and satisfy minReadySeconds before the controller can count it as available under these settings.
Rollback restores a retained Pod template
Separate rollout failure reporting from an explicit template rollback.
Revision two references a bad image. New Pods fail while old available replicas remain under the configured budget.
- Rollout lacks progress to Revision 2 pull failurenew revision
- Rollout lacks progress to Revision 1 availableretained capacity
Read the complete visual sequence
- A new template fails to become available
Revision two references a bad image. New Pods fail while old available replicas remain under the configured budget.
- Read history and choose recovery
The progress deadline reports failure; it does not perform automatic rollback. An operator chooses an actual known-good retained revision.
- Reconcile the previous template
The Deployment restores the selected template and coordinates ReplicaSets again. External data and changed-in-place ConfigMaps remain independent.
Failure: rollback cannot rewind data
Failure: rollback cannot rewind data
- A release changes a schema
Application version two performs a database migration. That data change is outside the Deployment Pod template.
- Undo restores version one code
The Pod template returns to old code, but the external database remains migrated. Version one may be incompatible.
- Design compatible data transitions
Use an explicit data migration and recovery plan, including coexistence and compatibility checks. Template history is not a database backup.
About this model
Revision numbers are illustrative; learners must inspect their own retained history.
Practice: stall deliberately, then restore a template
In a dedicated lab, update to an intentionally nonexistent image tag. New Pods should fail image preparation while the old available replicas are retained as far as the strategy permits. The Deployment reports lack of progress after its configured deadline; Kubernetes does not automatically select a previous application release merely because progressDeadlineSeconds expires.
kubectl describe deployment rollout-demo
kubectl get pods -l app=rollout-demo
kubectl rollout history deployment/rollout-demo
# Choose the actual known-good revision from your own history.
kubectl rollout undo deployment/rollout-demo --to-revision=ACTUAL_GOOD_REVISION
kubectl rollout status deployment/rollout-demo --timeout=180s
Rollback restores a retained earlier Pod template through another reconciliation. It does not rewind a database migration, restore external state, revert a ConfigMap changed in place, or revoke credentials. Old and new application versions can overlap during both forward rollout and rollback, so compatible protocols and schema transitions are application responsibilities. Keep the source manifest consistent after recovery; otherwise the next apply can reintroduce the failed release.
Pitfalls
A surge budget requires enough capacity for extra Pods. With maxUnavailable: 0, a full cluster can stall safely because no new Pod can fit and old replicas cannot be removed yet. With a looser unavailable budget, you trade some availability headroom for room to progress. Percent-based settings also have documented rounding rules; use simple integer budgets while learning and calculate actual bounds before using percentages.
Revision history is bounded by retained ReplicaSets. Deleting old history removes straightforward template rollback options. A successful rollout status only confirms controller progress and availability criteria; use request tests and observability to establish that the release behaves correctly for users.
Check your understanding
A new replica never becomes ready with maxUnavailable zero. Should the controller delete an old healthy replica to force progress?
Not under that availability policy. Keeping old available capacity is the intended safety property. Inspect why the new Pod is unready or unschedulable, and repair the release or choose a deliberate different budget. A stalled rollout can be a safer outcome than discarding the last known-good replicas.
Practice a bad-image rollout and explicit recovery in the module lab, then compare rollout health with the probe semantics in the next lesson.
Primary documentation
Go to the source
Reviewed 2026-10-27 · Kubernetes 1.37 · Related local exercise