Managing Rollouts with kubectl rollout

The kubectl rollout command gives you control over deployment updates in progress. You can monitor status, pause and resume rollouts, and restart deployments.

Checking Rollout Status

Watch a rollout's progress in real time:

kubectl rollout status deployment/web-app

This command blocks until the rollout completes or fails. It exits with code 0 on success and non-zero on failure, making it useful in CI/CD scripts:

kubectl set image deployment/web-app web=web-app:2.0
kubectl rollout status deployment/web-app --timeout=5m

Pausing and Resuming Rollouts

Pause a rollout to perform a canary-style verification with a subset of updated pods:

# Start the update
kubectl set image deployment/web-app web=web-app:2.0

# Pause after some pods have updated
kubectl rollout pause deployment/web-app

# Verify the new pods are healthy
kubectl get pods -l app=web-app

# Resume when satisfied
kubectl rollout resume deployment/web-app

While paused, the deployment controller stops creating new ReplicaSets or scaling them. You can make multiple changes to the spec during a pause, and they all take effect as a single rollout when you resume.

Restarting a Deployment

Trigger a rolling restart without changing the image. This recreates all pods:

kubectl rollout restart deployment/web-app

This is useful for picking up updated ConfigMaps, Secrets, or refreshing pod state.

Change Cause Annotations

Record why a rollout was triggered by using the annotation:

kubectl annotate deployment/web-app kubernetes.io/change-cause="Upgrade to v2.0 for bug fix"

Or include it when setting the image:

kubectl set image deployment/web-app web=web-app:2.0
kubectl annotate deployment/web-app kubernetes.io/change-cause="Deploy v2.0"

This annotation appears in kubectl rollout history, making it easier to understand past changes. Track change causes consistently to maintain an audit trail of deployments.