# kubectl rollout pause: Usage, Options & Common CI Errors

> kubectl rollout pause freezes a Deployment so multiple edits batch into one rollout. Canary staging in CI, and the forgotten-pause that blocks deploys.

Source: https://latchkey.dev/learn/command-reference/kubectl-rollout-pause  
Updated: 2026-06-25

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.

## Using this in CI

A runner has no kubeconfig, no cached context, and no interactive auth. Every kubectl invocation in CI needs the context supplied explicitly, and most confusing CI failures here are the command running against the wrong cluster or no cluster at all.

```Terminal
# never rely on the ambient context on a runner
kubectl --context "$KUBE_CONTEXT" -n "$NAMESPACE" get pods

# confirm what you are actually connected to before mutating anything
kubectl config current-context
kubectl cluster-info

# fail fast instead of hanging on an unreachable API server
kubectl --request-timeout=30s get nodes
```

> Always set `--request-timeout` in CI. Without it an unreachable API server hangs until the job times out, which turns a thirty-second failure into a twenty-minute one.

## FAQ

### kubectl rollout pause: Usage, Options & Common CI Errors?

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 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 ...

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt