⌂ Home

Kubernetes Deployment Rollback

Understanding how Kubernetes handles rollbacks and revision history

Interactive Rollback Flow Diagram

Hover over each step to see the kubectl command and detailed explanation.

1. Detect Issue Version 2 Broken Problem Found 2. Execute Rollback kubectl rollout undo API Call 3. Create Revision 3 (Using v1 Template) Switch RS 4. ReplicaSet Switching v2 RS → Scale Down v1 RS → Scale Up Replace Pods 5. Pod Replacement v2 Terminating v2 Terminating v1 Running v1 Running Verify 6. Verify Success Version 1 Restored Revision History Before Rollback: Rev 1: v1 (inactive) Rev 2: v2 (active) After Rollback: Rev 2: v2 (inactive) Rev 3: v1 (active)

Key Takeaways

  • Revision Numbers Always Increment: Rollback creates revision 3, not revert to revision 1
  • Zero Downtime: Rolling update strategy ensures continuous availability
  • ReplicaSet Reuse: Kubernetes reuses existing ReplicaSets instead of creating duplicates
  • Complete Audit Trail: All changes are tracked chronologically
  • Fast Recovery: Rollback is much faster than a full redeployment

Rollback Process Flow

When you perform a rollback, Kubernetes creates a new revision using the pod template from a previous revision. The revision numbers always increment forward - they never go backwards.

1

Initial State - Version 2 (Broken)

Your deployment is running version 2, but there's a problem. Current revision: 2

↓
2

Execute Rollback Command

kubectl rollout undo deployment/apache-deployment

↓
3

Kubernetes Creates New Revision (3)

Kubernetes copies the pod template from revision 1 and creates revision 3 with it

↓
4

Rolling Update Process Begins

Old ReplicaSet (v2) scales down while old ReplicaSet (v1 template) scales up

↓
5

Rollback Complete - Version 1 Restored

Application now runs version 1 under revision 3. Revision history: 1, 2, 3

Key Concept

Rollback doesn't mean going back to revision 1. It means creating a new revision (3) that uses the same pod template as revision 1. This maintains a complete audit trail of all changes.

Interactive Revision History Timeline

Click on any revision to see detailed information about that version.

March 23, 2026 - 09:00 AM
Revision 1
Image: karthickponcloud/k8slabs:apache_v1
Replicas: 2
Status: Initial deployment
Initial Deployment
1
March 23, 2026 - 10:30 AM
Revision 2
Image: karthickponcloud/k8slabs:apache_v2
Replicas: 2
Status: Updated to version 2
Change: New features added
Feature Update
2
March 23, 2026 - 11:15 AM
Revision 3 (Current)
Image: karthickponcloud/k8slabs:apache_v1
Replicas: 2
Status: Active and running
Change: Rolled back from v2 to v1
Reason: Issues detected in v2
Rollback to v1
3

Revision History Visualization

1 Revision 1 apache_v1 09:00 AM INITIAL Update 2 Revision 2 apache_v2 10:30 AM UPDATE Rollback 3 Revision 3 apache_v1 11:15 AM ROLLBACK Legend: Initial Update Rollback Current

Understanding Revision History

  • Sequential Numbering: Revisions always increment (1, 2, 3, ...) - never go backwards
  • Same Image, Different Revision: Revision 3 uses the same image as Revision 1, but it's a new revision
  • ReplicaSet Reuse: Revision 3 reuses the ReplicaSet created in Revision 1
  • History Limit: Default limit is 10 revisions (configurable via revisionHistoryLimit)
  • Audit Trail: Complete chronological record of all deployment changes

Viewing Revision History

# View all revisions kubectl rollout history deployment/apache-deployment # View specific revision details kubectl rollout history deployment/apache-deployment --revision=3 # Compare two revisions kubectl get rs -l app=apache -o wide

Understanding Revision History

Kubernetes maintains a history of all deployment revisions. Each time you update or rollback a deployment, a new revision is created.

Revision Progression Example

Revision 1
Image: apache_v1
Status: Historical
Change: Initial deployment
Revision 2
Image: apache_v2
Status: Historical
Change: Updated to version 2
Revision 3
Image: apache_v1
Status: Current
Change: Rolled back to v1

How Revision History Works

  • Sequential numbering: Revisions are numbered 1, 2, 3, etc. They never go backwards
  • ReplicaSet storage: Each revision corresponds to a ReplicaSet that stores the pod template
  • History limit: By default, Kubernetes keeps the last 10 revisions (configurable via revisionHistoryLimit)
  • Rollback creates new revision: Rolling back to revision 1 creates revision 3 with the same pod template

After Multiple Updates and Rollbacks

Revision 1
Image: apache_v1
Change: Initial
Revision 2
Image: apache_v2
Change: Update to v2
Revision 3
Image: apache_v1
Change: Rollback to v1
Revision 4
Image: apache_v2
Change: Rollback to v2

Important Note

When you use kubectl rollout undo without specifying a revision, it rolls back to the immediately previous revision. When you use --to-revision=N, it rolls back to that specific revision's pod template.

Pod Replacement Visualization

Watch how pods transition from version 2 (broken) to version 1 (stable) during rollback.

Rolling Update During Rollback Phase 1: Before Rollback v2 ReplicaSet (ACTIVE) v2 Pod 1 RUNNING v2 Pod 2 RUNNING kubectl rollout undo Phase 2: Rollback Initiated v2 ReplicaSet (Scaling Down) v2 Pod 1 TERMINATING v2 Pod 2 RUNNING Desired: 0 | Current: 2→1 Scaling Phase 3: Pod Transition v2 RS (Scaling Down) v2 Pod 2 TERMINATING v1 RS (Scaling Up) v1 Pod 1 RUNNING Finalizing Phase 4: Rollback Complete v1 ReplicaSet (ACTIVE) v1 Pod 1 RUNNING v1 Pod 2 RUNNING Rolling Update Strategy maxSurge: 1 Can create 1 extra pod during update (3 total) maxUnavailable: 0 All pods must be available Zero downtime rollback ✓ Zero Downtime Pod Status Legend: v2 Running (Failing) Terminating v1 Running (Healthy)

Pod Replacement Strategy

  • Gradual Transition: Pods are replaced one or a few at a time, not all at once
  • Readiness Checks: New pods must pass readiness probes before old pods are terminated
  • Graceful Shutdown: Old pods receive SIGTERM and have 30 seconds (default) to finish requests
  • Zero Downtime: With maxUnavailable: 0, at least 2 pods are always available
  • Automatic Rollback: If new pods fail to start, the process automatically stops

Monitoring Pod Replacement

# Watch rollback progress in real-time kubectl rollout status deployment/apache-deployment -w # Watch pod changes kubectl get pods -l app=apache -w # View ReplicaSet scaling kubectl get rs -l app=apache -w

Normal Rollout vs Rollback Flow

Compare how forward rollouts and rollbacks work in Kubernetes deployments.

Forward Rollout: Updating from v1 to v2

1. Deployment Running v1 Revision 1 | 2 pods | Stable 2. Update Command Issued kubectl set image ... apache_v2 3. Create New Revision 2 New ReplicaSet for v2 created 4. Rolling Update v1 RS: 2 → 1 → 0 v2 RS: 0 → 1 → 2 Gradual pod replacement Result: Revision 2 (v2) Active

Forward Rollout Characteristics

  • Purpose: Deploy new features or updates
  • Direction: Moving forward to newer version
  • Revision: Creates sequential new revision (1 → 2)
  • ReplicaSet: Creates new ReplicaSet for v2
  • Risk: New code might have bugs
  • Testing: Should be tested before production

Rollback Flow: Reverting from v2 to v1

1. Issue Detected in v2 Revision 2 | 2 pods | Failing 2. Rollback Command kubectl rollout undo deployment 3. Create New Revision 3 Reuses v1 ReplicaSet template 4. Rolling Rollback v2 RS: 2 → 1 → 0 v1 RS: 0 → 1 → 2 Return to stable version Result: Revision 3 (v1 template) Active

Rollback Flow Characteristics

  • Purpose: Recover from problematic deployment
  • Direction: Reverting to previous stable version
  • Revision: Creates new revision (3) with old template
  • ReplicaSet: Reuses existing v1 ReplicaSet
  • Risk: Very low - returning to known-good state
  • Speed: Fast - no image pull needed (cached)

Forward Rollout

  • Trigger: Manual update command
  • Image: Pulls new image from registry
  • ReplicaSet: Creates new RS
  • Revision: Increments by 1
  • Time: Depends on image size
  • Risk Level: Medium-High

Rollback

  • Trigger: Issue detection
  • Image: Uses cached image
  • ReplicaSet: Reuses existing RS
  • Revision: Increments by 1
  • Time: Very fast
  • Risk Level: Low

Key Similarity

Both forward rollouts and rollbacks follow the same rolling update strategy. The only difference is the direction: rollout moves to a newer template, rollback moves to an older template. Both create new revisions and ensure zero downtime.

Before and After Rollback Comparison

See exactly what changes during a rollback at the ReplicaSet and Pod level.

Before Rollback

Current Revision: 2 (apache_v2)

apache-deployment-5d4f6b7c8d (v2)
Desired: 2 | Current: 2 | Ready: 2
P1
P2
apache-deployment-6c5d7f8a9b (v1)
Desired: 0 | Current: 0 | Ready: 0
No pods running
Deployment Status:
Image: apache_v2
Replicas: 2/2
Available: 2

After Rollback

Current Revision: 3 (apache_v1)

apache-deployment-5d4f6b7c8d (v2)
Desired: 0 | Current: 0 | Ready: 0
No pods running
apache-deployment-6c5d7f8a9b (v1)
Desired: 2 | Current: 2 | Ready: 2
P1
P2
Deployment Status:
Image: apache_v1
Replicas: 2/2
Available: 2

What Happened?

  • The v2 ReplicaSet (apache-deployment-5d4f6b7c8d) scaled down from 2 to 0
  • The v1 ReplicaSet (apache-deployment-6c5d7f8a9b) scaled up from 0 to 2
  • The same ReplicaSet from revision 1 was reused (Kubernetes doesn't create a duplicate)
  • A new revision number (3) was created, but it points to the existing v1 ReplicaSet
  • Rolling update strategy ensured zero downtime during the rollback

During Rollback (Mid-Process)

v2 ReplicaSet
P1
Scaling down: 1 → 0
⟷
v1 ReplicaSet
P1
Scaling up: 1 → 2

Kubernetes ensures new pods are ready before terminating old ones

Rollback Commands and Outputs

1. Check Current Status

# View deployment status $ kubectl get deployment apache-deployment NAME READY UP-TO-DATE AVAILABLE AGE apache-deployment 2/2 2 2 10m # View current image $ kubectl describe deployment apache-deployment | grep Image Image: karthickponcloud/k8slabs:apache_v2

2. View Rollout History

$ kubectl rollout history deployment/apache-deployment deployment.apps/apache-deployment REVISION CHANGE-CAUSE 1 Initial deployment 2 Apache version 2

Understanding the History Output

  • REVISION: Sequential number for each change
  • CHANGE-CAUSE: Annotation describing the change (set via --record flag or kubernetes.io/change-cause annotation)
  • The current revision is not specifically marked - you need to check deployment status

3. Perform Rollback (Undo)

# Rollback to previous revision $ kubectl rollout undo deployment/apache-deployment deployment.apps/apache-deployment rolled back # Watch the rollout status $ kubectl rollout status deployment/apache-deployment Waiting for deployment "apache-deployment" rollout to finish: 1 out of 2 new replicas have been updated... Waiting for deployment "apache-deployment" rollout to finish: 1 old replicas are pending termination... deployment "apache-deployment" successfully rolled out

4. Rollback to Specific Revision

# View detailed history for a specific revision $ kubectl rollout history deployment/apache-deployment --revision=1 deployment.apps/apache-deployment with revision #1 Pod Template: Labels: app=apache Containers: apache-container: Image: karthickponcloud/k8slabs:apache_v1 Port: 80/TCP Annotations: kubernetes.io/change-cause: Initial deployment # Rollback to specific revision $ kubectl rollout undo deployment/apache-deployment --to-revision=2 deployment.apps/apache-deployment rolled back

5. Verify Rollback

# Check deployment image $ kubectl describe deployment apache-deployment | grep Image Image: karthickponcloud/k8slabs:apache_v1 # View updated history $ kubectl rollout history deployment/apache-deployment deployment.apps/apache-deployment REVISION CHANGE-CAUSE 2 Apache version 2 3 Initial deployment # Note: Revision 1 is now gone, replaced by revision 3 with the same template

6. View ReplicaSets

$ kubectl get replicasets -l app=apache NAME DESIRED CURRENT READY AGE apache-deployment-6c5d7f8a9b 2 2 2 15m # v1 (active) apache-deployment-5d4f6b7c8d 0 0 0 10m # v2 (inactive) # Each ReplicaSet corresponds to a specific pod template (revision)

Important Notes

  • kubectl rollout undo without --to-revision rolls back to the immediately previous revision
  • --to-revision=N lets you jump to any revision in the history
  • After rollback, the old revision number disappears and is replaced with a new one
  • Use --record flag or add annotations to track change causes

Technical Deep Dive: How Rollback Works

The Relationship: Deployment → ReplicaSet → Pods

Deployment
Manages multiple
ReplicaSets
→
ReplicaSet
Each revision creates
or reuses a ReplicaSet
→
Pods
ReplicaSet manages
actual pod instances

Step-by-Step: What Happens During Rollback

1

Deployment Controller Receives Rollback Command

When you run kubectl rollout undo, the command is sent to the Kubernetes API server.

↓
2

Deployment Identifies Target Revision

The deployment controller looks up the target revision from its history. If no revision is specified, it uses the previous revision.

↓
3

Creates New Revision Entry

A new revision number is assigned (e.g., revision 3), even though the pod template comes from an older revision (e.g., revision 1).

↓
4

Reuses Existing ReplicaSet

Kubernetes finds the ReplicaSet from the target revision (it was scaled to 0) and prepares to scale it back up.

↓
5

Applies Rolling Update Strategy

The rollback follows the same rolling update strategy defined in the deployment (maxSurge, maxUnavailable).

↓
6

Scales Old and New ReplicaSets

Old ReplicaSet (current/broken version) scales down while target ReplicaSet (previous/working version) scales up.

↓
7

Monitors Pod Readiness

New pods are created and must pass readiness checks before old pods are terminated.

↓
8

Rollback Complete

All pods from the old version are terminated, and all pods from the target version are running and ready.

Key Technical Concepts

1. ReplicaSet Reuse

Kubernetes doesn't create a new ReplicaSet for a rollback if one with the same pod template already exists. It reuses the existing ReplicaSet from the target revision.

2. Revision Number Always Increments

Even though you're "rolling back," the revision number moves forward. This maintains a chronological audit trail of all changes to the deployment.

3. Rolling Update Strategy Applies

Rollback isn't instant - it follows the deployment's strategy configuration:

  • maxSurge: Maximum number of pods that can be created above the desired count
  • maxUnavailable: Maximum number of pods that can be unavailable during the update

4. Revision History Limit

The revisionHistoryLimit field (default: 10) controls how many old ReplicaSets to keep. When this limit is exceeded, the oldest ReplicaSets are deleted, and you can no longer roll back to those revisions.

Example Deployment Configuration

apiVersion: apps/v1 kind: Deployment metadata: name: apache-deployment spec: replicas: 2 revisionHistoryLimit: 10 # Keep last 10 revisions strategy: type: RollingUpdate rollingUpdate: maxSurge: 1 # Can create 1 extra pod during update maxUnavailable: 0 # Always maintain full availability selector: matchLabels: app: apache template: metadata: labels: app: apache spec: containers: - name: apache-container image: karthickponcloud/k8slabs:apache_v1 ports: - containerPort: 80

Common Misconceptions

❌ Misconception: "Rollback reverts to revision 1"

Reality: Rollback creates a new revision (e.g., 3) that uses the pod template from revision 1. The revision number never goes backwards.

❌ Misconception: "Rollback is instantaneous"

Reality: Rollback follows the rolling update strategy, gradually replacing pods to maintain availability.

❌ Misconception: "Rollback creates a new ReplicaSet"

Reality: Kubernetes reuses the existing ReplicaSet from the target revision, just scaling it back up.

✓ Best Practices

  • Always use --record flag or annotations to document changes
  • Test rollbacks in non-production environments first
  • Monitor rollout status with kubectl rollout status
  • Set appropriate revisionHistoryLimit based on your needs
  • Configure proper readiness and liveness probes for safe rollbacks
  • Use --to-revision to rollback to a specific known-good version