kubectl rollout pause: Usage, Options & Common CI Errors

Freeze a Deployment so several edits ship as a single rollout.

kubectl rollout pause stops a Deployment from rolling out new pods, letting you make several spec changes that then apply together when you resume. It is used to stage a canary or to batch edits without triggering N separate rollouts.

What it does

kubectl rollout pause deploy/NAME sets spec.paused=true. While paused, edits to the pod template (set image, set env, patch) are recorded but no new ReplicaSet is rolled out. The change set ships as one rollout when you run rollout resume.

Common usage

Terminal

kubectl rollout pause deploy/web
kubectl set image deploy/web web=myreg/web:${GIT_SHA}
kubectl set resources deploy/web -c=web --limits=cpu=1,memory=1Gi
kubectl rollout resume deploy/web              # all changes ship together

Common errors in CI

The dominant failure is a forgotten resume: a paused Deployment ignores every subsequent change, so a later pipeline "deploys" but nothing rolls out, and kubectl rollout status hangs because a paused rollout never progresses. Always pair pause with resume in the same job, ideally in a trap/finally. "cannot pause/resume ... already paused" on re-run is harmless but signals your pipeline is not idempotent. You also cannot roll back a paused Deployment - resume it first, then undo.

Related guides

kubectl Cheat Sheet: Commands for Everyday KubernetesA kubectl cheat sheet - get, describe, logs, apply, rollout, debug, and context commands for daily Kubernetes… kubectl rollout resume: Usage, Options & Common CI Errorskubectl rollout resume un-pauses a Deployment and ships the batched changes as one rollout. Pairing with paus… kubectl rollout restart: Usage, Options & Common CI Errorskubectl rollout restart triggers a rolling restart without changing the spec. Picking up rotated secrets and… kubectl set image: Usage, Options & Common CI Errorskubectl set image promotes a Deployment to a new image tag and triggers a rollout. The CI deploy step, contai…