Q: How do you roll back to a previous Docker image version in Kubernetes?
To roll back to a previous Docker image version in Kubernetes, run kubectl rollout undo deployment/my-app (optionally with --to-revision=N), or redeploy the known-good image digest from Git.
Want to master this scenario in a live sandbox? KodeKloud's Docker Certified Associate (DCA) Hands-On Lab Course covers this exact problem with hands-on terminal drills.
🛠️ Production Runbook & Step-by-Step Resolution
Direct Answer: To <strong>roll back to a previous Docker image version in Kubernetes</strong>, run <code>kubectl rollout undo deployment/my-app</code> (optionally with <code>--to-revision=N</code>), or redeploy the known-good image digest from Git. A Deployment keeps old ReplicaSets, so a rollback is just scaling an older ReplicaSet back up under the same rolling-update rules. Interviewers ask this to see whether you understand revision history, immutable image references and what a rollback does not undo, such as ConfigMaps, database schema changes and anything managed by GitOps controllers that will simply put the bad version back.
Mental model: Deployments, ReplicaSets and revisions
Every change to the pod template creates a new ReplicaSet; a rollback re-activates one of the old ones.
- Revision = ReplicaSet: Changing
spec.template(image, env, resources) creates a new ReplicaSet and a new revision number. Scaling or changingreplicasdoes not. - History limit:
spec.revisionHistoryLimitdefaults to 10. If it is set to0, old ReplicaSets are garbage collected androllout undohas nothing to roll back to. - Strategy still applies: A rollback uses the same
maxSurgeandmaxUnavailablesettings as a forward rollout, so it is gradual and respects readiness probes. - Revision numbers move: Rolling back to revision 3 makes that pod template the newest revision (for example revision 6); revision 3 disappears from the list because it is now the current one.
Hands-on: roll back to a previous Docker image version in Kubernetes
Inspect history first, then undo to the last revision or to a specific one.
kubectl rollout history deployment/my-app -n prod
# REVISION CHANGE-CAUSE
# 4 release 1.4.2
# 5 release 1.5.0
kubectl rollout history deployment/my-app -n prod --revision=4 | grep Image
# Image: registry.example.com/my-app:1.4.2
kubectl rollout undo deployment/my-app -n prod --to-revision=4
# Fallback when history is unavailable: deploy by immutable digest
kubectl set image deployment/my-app \
my-app=registry.example.com/my-app@sha256:<known-good-digest> -n prod
- See what you can return to:
kubectl rollout history deployment/my-app -n prodlists revisions; add--revision=Nto print the image and env of that revision. - Undo the last change:
kubectl rollout undo deployment/my-app -n prodgoes back exactly one revision. - Pick a specific revision:
--to-revision=Nis safer during incidents because a failed forward fix can leave the previous revision also bad. - Pin an exact image: If history is gone,
kubectl set imagewith a digest deploys a known-good build directly.
Verify the rollback actually completed
A successful command only means the API accepted the change; confirm the pods are running the old image and healthy.
kubectl rollout status deployment/my-app -n prod --timeout=180s
kubectl get pods -n prod -l app=my-app \
-o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.status.containerStatuses[0].imageID}{"\n"}{end}'
kubectl get rs -n prod -l app=my-app
- Wait for convergence:
kubectl rollout status deployment/my-app -n prod --timeout=180sexits non-zero if the rollout stalls, which makes it usable in scripts. - Check the running image ID: Compare
.status.containerStatuses[*].imageIDagainst the digest you expect, because a mutable tag can resolve to a different build. - Read the events:
kubectl describe deployment my-appshows the ReplicaSet scale-up and scale-down sequence, andkubectl get rs -n prodconfirms the old ReplicaSet owns the desired replica count. - Watch golden signals: Error rate and latency on your dashboards should return to baseline; Kubernetes health alone does not prove the service is correct.
Failure modes and edge cases
Most failed rollbacks come from state outside the pod template or from tags that are not immutable.
- Mutable tags: If
my-app:stablewas overwritten, undoing to a revision that references that tag may pull the new bad content whenimagePullPolicy: Alwaysis set. Immutable tags or digests avoid this. - Schema changes: If the new version ran a forward-only migration, the old code may crash against the new schema. Use expand/contract migrations so the previous version stays compatible.
- GitOps fights you: With Argo CD or Flux self-heal enabled, a manual
rollout undois reverted to the Git state within minutes. Revert the commit instead, or pause sync. - Registry pruning: A lifecycle policy that deletes old images can leave a ReplicaSet pointing at an image that no longer exists, producing
ImagePullBackOff. - Paused Deployments: A Deployment with
spec.paused: truewill not roll back until you runkubectl rollout resume.
Production practice: make rollback boring
Design the pipeline so that rolling back is the same code path as rolling forward.
- Git revert as the source of truth: In GitOps, revert the commit that changed the image; the controller applies it with audit history.
- Record intent: Annotate releases with
kubectl annotate deployment/my-app kubernetes.io/change-cause="release 1.5.0"(the older--recordflag is deprecated) so history is readable. - Automate the trigger: Argo Rollouts or Flagger can abort and roll back automatically when Prometheus analysis fails, removing human delay.
- Rehearse: Run a rollback in staging regularly and keep
revisionHistoryLimitat 5 to 10, and retain the last several release images in the registry.
- A rollback in Kubernetes re-activates an older ReplicaSet, using the Deployment's normal rolling-update rules, via kubectl rollout undo with an optional --to-revision.
- I verify with rollout status, the running imageID digest and error-rate dashboards, and I check that GitOps will not revert my change.
- I automate it by reverting in Git, using immutable digests, and letting Argo Rollouts or Flagger abort failing releases automatically.
Senior hiring managers and bar raisers evaluate how you prioritize during outages. Avoid these common anti-patterns:
- Setting revisionHistoryLimit to 0 to reduce clutter Old ReplicaSets are deleted, so there is no revision to undo to and recovery requires a full redeploy.
- Rolling back with kubectl while Argo CD self-heal is on The controller reapplies the Git state and silently reinstates the bad image.
- Assuming the rollback also reverts the database Forward-only migrations leave the schema incompatible with the older code, causing crashes after the undo.
- Trusting a mutable tag like stable or latest The tag may now point to different content, so the previous revision does not run the previous build.