Revision History and Rollback in Kubernetes: Restoring Previous Versions of a Deployment
What if the new application version has a problem right after deployment? Will you have to manually edit the manifest to roll back?
Fortunately, no.
One of the most useful features of Deployments is maintaining a history of changes. This history allows you to track each update and, when necessary, quickly revert to a previous version using rollback.
In this article, we’ll understand how Kubernetes records these revisions, view a Deployment’s history, and learn how to restore previous versions.
What is a Revision?
Whenever a change in the Deployment generates a new version of the Pods, Kubernetes creates a new revision.
Each revision represents a specific state of that Deployment.
Imagine the following update sequence.
Revision 1
nginx:1.30.4
│
Update
▼
Revision 2
nginx:1.31.0
│
Update
▼
Revision 3
nginx:1.31.1Each significant change generates a new revision that can be consulted later.
What Triggers a New Revision?
Not every change creates a new revision.
Typically, changes to the Pod template generate a new version.
For example:
- image changes;
- environment variable changes;
- resource changes (CPU and memory);
- adding or removing containers;
- volume modifications;
- changes to template Labels.
These modifications cause a new ReplicaSet to be created.
Viewing the History
To view existing revisions, we use:
kubectl rollout history deployment \
nginx-deployment \
-n giropopsExplaining:
rollout history→ displays the revision history.deployment→ resource type.nginx-deployment→ Deployment name.-n giropops→ Namespace.
Expected output:
deployment.apps/nginx-deployment
REVISION CHANGE-CAUSE
1 <none>
2 <none>
3 <none>Each number represents a revision stored by the Deployment.
Viewing a Specific Revision
It’s also possible to view an individual revision.
kubectl rollout history deployment \
nginx-deployment \
--revision=2 \
-n giropopsExpected output:
Pod Template
Image:
nginx:1.31.0
...This command is very helpful when we need to find out exactly which version was being used.
Tracking an Update
Before performing a rollback, we usually check if the rollout completed successfully.
kubectl rollout status deployment \
nginx-deployment \
-n giropopsExpected output:
deployment "nginx-deployment" successfully rolled outIf there’s any problem during the update, this command will also indicate that the rollout is still in progress.
Performing a Rollback
Imagine we updated the application.
Before:
Revision 2
nginx:1.30.4After:
Revision 3
nginx:1.31.0Right after the deploy, we noticed a problem.
We can revert to the previous revision using:
kubectl rollout undo deployment \
nginx-deployment \
-n giropopsExpected output:
deployment.apps/nginx-deployment rolled backKubernetes will automatically restore the previous revision.
Restoring a Specific Revision
We can also revert directly to a specific revision.
For example.
kubectl rollout undo deployment \
nginx-deployment \
--revision=2 \
-n giropopsExplaining:
undo→ undoes an update.--revision=2→ reverts exactly to revision 2.
Expected output:
deployment.apps/nginx-deployment rolled backIt’s important to understand one detail.
Kubernetes doesn’t “go back in time”.
It uses the configuration stored in that revision to create a new rollout.
In other words, a rollback also generates a new revision in the history.
Example:
Revision 1
↓
Revision 2
↓
Revision 3
↓
Rollback to Revision 2
↓
Revision 4Revision 4 has the same configuration as Revision 2, but it’s considered a new revision.
This behavior facilitates audits and change tracking.
How Rollback Works Internally?
The flow can be represented as follows.
Deployment
│
Revision 1
│
Revision 2
│
Revision 3
│
Rollback
▼
New ReplicaSet
▼
Revision 4Notice that Kubernetes never directly reuses an old ReplicaSet.
It creates a new rollout based on that revision’s configuration.
Limiting the Number of Revisions
The Deployment can store multiple revisions.
However, maintaining a very large history consumes unnecessary resources.
To control this, there’s the revisionHistoryLimit field.
spec:
revisionHistoryLimit: 5In this example, Kubernetes will only keep the five most recent revisions.
The oldest ones will be automatically removed.
When to Use revisionHistoryLimit?
This parameter is quite useful in production environments.
Some examples.
| Scenario | Suggested Value |
|---|---|
| Labs | 2 to 3 |
| Small Applications | 5 |
| Production | 10 |
| Highly Critical Environments | As per company policy |
There’s no universal value.
The choice depends on the deployment frequency and the need for auditing.
Command Summary
| Command | Function |
|---|---|
kubectl rollout status | Tracks the update |
kubectl rollout history | Lists revisions |
kubectl rollout history --revision | Shows a specific revision |
kubectl rollout undo | Reverts to the previous revision |
kubectl rollout undo --revision | Reverts to a specific revision |
Summary
Deployment
│
├── Revision 1
├── Revision 2
├── Revision 3
│
└── Rollback
│
▼
New revision createdEach significant update generates a new revision.
When needed, we can quickly revert to previous versions using just one command.
Conclusion
The revision history is one of the most valuable features of Deployments.
It offers traceability, facilitates audits, and allows for quickly recovering a stable application version in case of issues.
We also saw that rollback doesn’t directly reuse an old revision: it creates a new rollout based on that configuration, preserving the entire Deployment history.
In the next and final article of the series, we will bring together all the concepts studied and explore best practices for working with Deployments in production environments, including manifest organization, Namespace usage, update strategies, and day-to-day recommendations.