Kubernetes Deployment Revision Control

Kubernetes Deployment Revision Control is the internal bookkeeping system through which the Deployment controller assigns, stores, and retires sequential revision numbers for each distinct Pod template a Deployment has used, implemented entirely as annotations on the ReplicaSet objects it manages rather than as a separate history object. This mechanism is what makes rollback and history inspection possible, since it is the literal source of the data those operations read.

Where Revision Numbers Actually Live

The revision Annotation on ReplicaSets

Each ReplicaSet created by a Deployment carries a deployment.kubernetes.io/revision annotation, a monotonically increasing integer assigned when that ReplicaSet is first created. There is no separate revision history object; the set of all ReplicaSets owned by a Deployment, each with its revision annotation, is the entire history.

apiVersion: apps/v1
kind: ReplicaSet
metadata:
  name: revision-control-example-7d4b9c8f6d
  annotations:
    deployment.kubernetes.io/revision: "4"
  ownerReferences:
    - apiVersion: apps/v1
      kind: Deployment
      name: revision-control-example
      controller: true

When a New Revision Is Assigned

Template Hash as the Trigger

A new revision number is only assigned when a change to spec.template produces a pod-template-hash that does not match any existing ReplicaSet owned by the Deployment. Scaling spec.replicas alone, without a template change, does not create a new ReplicaSet and therefore does not advance the revision counter.

kubectl get replicaset -l app=web -o custom-columns=NAME:.metadata.name,REVISION:.metadata.annotations.deployment\\.kubernetes\\.io/revision

Reverting to a Prior Template Reuses Its ReplicaSet

If a Pod template is changed back to exactly match an existing, still-retained ReplicaSet, the Deployment controller reuses that ReplicaSet rather than creating a new one, but it still advances the overall revision counter and updates that ReplicaSet's revision annotation to reflect its new position in history.

Reading History Through the API

kubectl rollout history

kubectl rollout history works by listing the Deployment's owned ReplicaSets, sorting by their revision annotation, and printing the associated change-cause annotation for each, entirely reconstructed from ReplicaSet metadata rather than any dedicated audit log.

kubectl rollout history deployment/revision-control-example

REVISION  CHANGE-CAUSE
2         initial rollout
3         bump to 2.0.0
4         bump to 2.1.0 for CVE fix

Garbage Collection of Old Revisions

revisionHistoryLimit

spec.revisionHistoryLimit bounds how many old, scaled-to-zero ReplicaSets the Deployment controller retains for rollback purposes. Once this limit is exceeded, the oldest retained ReplicaSets are deleted outright, permanently removing that revision from history.

spec:
  revisionHistoryLimit: 5

Implication for Deep Rollback

Because history is bounded by revisionHistoryLimit, attempting kubectl rollout undo --to-revision=N for a revision number older than what remains retained will fail, since the underlying ReplicaSet object no longer exists to scale back up.

kubectl rollout undo deployment/revision-control-example --to-revision=1

error: unable to find specified revision 1 in history

Revision Control Diagram

This design keeps revision control lightweight and consistent with the rest of Kubernetes' object model, no bespoke history database, at the cost of history depth being strictly bounded by however many old ReplicaSets an operator chooses to retain.