Kubernetes Deployment Rollout Control

Kubernetes Deployment Rollout Control is the operational surface, commands, status conditions, and annotations, through which an operator observes and directs an in-progress Deployment update, distinct from the internal ReplicaSet-swapping mechanics the Deployment controller performs automatically. Rollout control is what turns an otherwise opaque background process into something that can be watched, paused, accelerated, or reversed on demand.

Triggering and Watching a Rollout

What Starts a Rollout

A rollout begins whenever spec.template changes in a way that alters the computed template hash, an image tag bump, an environment variable change, a resource limit adjustment. Changes to fields outside the template, such as spec.replicas alone, are treated as scaling operations and do not start a new rollout.

kubectl set image deployment/rollout-control-example app=registry.example.com/app:2.1.0

Watching Progress

kubectl rollout status blocks and streams progress until the rollout completes, fails, or the command is interrupted, reading directly from the Deployment's status conditions rather than polling ReplicaSets manually.

kubectl rollout status deployment/rollout-control-example

Waiting for deployment "rollout-control-example" rollout to finish: 2 out of 3 new replicas have been updated...
deployment "rollout-control-example" successfully rolled out

Status Conditions Driving Control Decisions

Progressing and Available

The Deployment's Progressing condition reflects whether the rollout is actively making forward progress, while Available reflects whether enough replicas have been ready for at least minReadySeconds to be considered stable. A rollout stuck making no progress for longer than progressDeadlineSeconds flips Progressing to False with reason ProgressDeadlineExceeded.

status:
  conditions:
    - type: Progressing
      status: "False"
      reason: ProgressDeadlineExceeded
      message: "ReplicaSet has timed out progressing."

Pausing and Resuming Mid-Rollout

Freezing State for Inspection or Batching

kubectl rollout pause halts the controller from making further scaling adjustments between old and new ReplicaSets, freezing the rollout at its current partial state. This is commonly used to inspect a canary batch of new Pods before committing to the full rollout, or to stack several template edits into one eventual rollout.

kubectl rollout pause deployment/rollout-control-example
kubectl rollout resume deployment/rollout-control-example

Reversing a Rollout

Undo to the Previous or a Specific Revision

kubectl rollout undo reverts a Deployment to its previous revision by scaling the corresponding retained ReplicaSet back up and the current one down, following the same controlled rollout mechanics as a forward update. A specific revision can be targeted explicitly rather than only the immediately prior one.

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

Recording Change Causes

The kubernetes.io/change-cause annotation, set manually or via --record (deprecated in favor of manual annotation in recent versions), attaches a human-readable note to each revision, making kubectl rollout history more useful for identifying which change corresponds to which revision number.

kubectl annotate deployment rollout-control-example kubernetes.io/change-cause="bump to 2.1.0 for CVE fix"

Restarting Without a Spec Change

Forcing Pod Recreation

kubectl rollout restart triggers a new rollout without altering the Pod template's meaningful content, by updating a restart timestamp annotation, useful for picking up changes external to the template itself, such as an updated Secret mounted by reference.

kubectl rollout restart deployment/rollout-control-example

Rollout Control Diagram

Together these commands form a complete operational vocabulary for managing a live rollout, letting an operator react to a bad deployment or coordinate a complex change without ever needing to manipulate the underlying ReplicaSets directly.