kubectl rollout pause

When to Use kubectl rollout pause

kubectl rollout pause temporarily halts the rollout process for a deployment. This is valuable when you need to make multiple changes to a deployment's pod template without triggering separate rolling updates for each change. You batch the changes while paused, then resume to trigger a single coordinated rollout.

Batching Multiple Changes

Without pausing, each change triggers its own rollout:

# Without pause: THREE separate rollouts
kubectl set image deployment/my-app app=nginx:1.26
# Rollout #1 starts
kubectl set resources deployment/my-app -c app --limits=cpu=500m,memory=256Mi
# Rollout #2 starts (interrupts #1)
kubectl set env deployment/my-app LOG_LEVEL=info
# Rollout #3 starts (interrupts #2)

With pausing, all changes are applied as a single rollout:

# With pause: ONE rollout with all changes
kubectl rollout pause deployment/my-app

kubectl set image deployment/my-app app=nginx:1.26
kubectl set resources deployment/my-app -c app --limits=cpu=500m,memory=256Mi
kubectl set env deployment/my-app LOG_LEVEL=info

kubectl rollout resume deployment/my-app
# Single rollout with all three changes
kubectl rollout status deployment/my-app

Pause and Resume Workflow

The typical workflow follows a clear pattern:

# Step 1: Pause the deployment
kubectl rollout pause deployment/my-app
echo "Deployment paused"

# Step 2: Make all necessary changes
kubectl set image deployment/my-app app=myapp:v2.0
kubectl set env deployment/my-app \
  DATABASE_URL=postgresql://new-db:5432/myapp \
  CACHE_TTL=300
kubectl patch deployment my-app -p '{"spec":{"template":{"spec":{"containers":[{"name":"app","resources":{"requests":{"cpu":"200m","memory":"256Mi"},"limits":{"cpu":"1","memory":"512Mi"}}}]}}}}'

# Step 3: Verify changes look correct
kubectl get deployment my-app -o yaml | grep -A 20 "containers:"

# Step 4: Resume to trigger the rollout
kubectl rollout resume deployment/my-app

# Step 5: Monitor the rollout
kubectl rollout status deployment/my-app --timeout=300s

Paused Deployment Behavior

While paused, the deployment:

• Continues running current pods: Existing pods are not affected.
• Accepts template changes: Changes to the pod template are recorded but not acted upon.
• Blocks new ReplicaSets: No new ReplicaSet is created for pending changes.
• Blocks rollback: You cannot undo while paused.
• Pauses progress deadline: The progressDeadlineSeconds timer does not run.

# Check if a deployment is paused
kubectl get deployment my-app -o jsonpath='{.spec.paused}'
# true

# Describe shows the paused state
kubectl describe deployment my-app | grep "Paused"

CI/CD Pipeline Usage

Pause is useful in CI/CD when multiple configuration steps need to happen atomically:

#!/bin/bash
# Deploy with multiple changes in one rollout

NAMESPACE="production"
DEPLOYMENT="my-app"
IMAGE_TAG="${BUILD_TAG}"

# Pause to batch changes
kubectl rollout pause deployment/${DEPLOYMENT} -n ${NAMESPACE}

# Apply all changes
kubectl set image deployment/${DEPLOYMENT} app=myapp:${IMAGE_TAG} -n ${NAMESPACE}
kubectl set env deployment/${DEPLOYMENT} BUILD_TAG=${IMAGE_TAG} -n ${NAMESPACE}

# Resume for single rollout
kubectl rollout resume deployment/${DEPLOYMENT} -n ${NAMESPACE}

# Wait for completion
if ! kubectl rollout status deployment/${DEPLOYMENT} -n ${NAMESPACE} --timeout=300s; then
  echo "Rollout failed, rolling back"
  kubectl rollout undo deployment/${DEPLOYMENT} -n ${NAMESPACE}
  exit 1
fi

Canary Deployments with Pause

Some teams use pause as part of manual canary deployment strategies:

# Start the rollout with maxSurge but pause partway
# (This requires custom scripting to pause at the right time)
kubectl set image deployment/my-app app=myapp:v2
# Wait for some new pods to be ready
kubectl rollout pause deployment/my-app

# Test the canary pods manually
# ...

# If tests pass, resume the full rollout
kubectl rollout resume deployment/my-app

Recovering from a Forgotten Pause

If a deployment is accidentally left paused:

# Check for paused deployments
kubectl get deployments -A -o jsonpath='{range .items[?(@.spec.paused==true)]}{.metadata.namespace}/{.metadata.name}{"\n"}{end}'

# Resume the forgotten deployment
kubectl rollout resume deployment/my-app -n production

Best Practices

Always resume paused deployments promptly. Use pause only for batching changes, not as a long-term deployment lock. Include resume in the same script as pause to prevent orphaned paused deployments. Monitor for paused deployments in your cluster health checks. Document why a deployment is paused if it must remain paused for an extended period.