kubectl rollout status

When to Use kubectl rollout status

kubectl rollout status monitors the progress of a rolling update. It watches the deployment until all new pods are ready and the old pods are terminated, then reports the result. This is essential in CI/CD pipelines where you need to know whether a deployment succeeded before proceeding.

Monitoring Rollouts

The basic usage watches the rollout in real-time:

# Watch rollout progress
kubectl rollout status deployment/my-app
# Waiting for deployment "my-app" rollout to finish: 2 of 3 updated replicas are available...
# deployment "my-app" successfully rolled out

# Check a DaemonSet rollout
kubectl rollout status daemonset/node-exporter -n monitoring

# Check a StatefulSet rollout
kubectl rollout status statefulset/elasticsearch -n logging

The output shows the progress as pods are updated and becomes ready. When all replicas are updated and available, it prints a success message and exits with code 0.

CI/CD Pipeline Integration

The exit code behavior makes rollout status ideal for automation:

# Deploy and verify
kubectl apply -f deployment.yaml
if ! kubectl rollout status deployment/my-app --timeout=300s; then
  echo "Deployment failed, rolling back"
  kubectl rollout undo deployment/my-app
  exit 1
fi
echo "Deployment successful"

# Full pipeline script
kubectl set image deployment/my-app app=myapp:${BUILD_TAG}
kubectl rollout status deployment/my-app --timeout=600s
RESULT=$?
if [ $RESULT -ne 0 ]; then
  echo "Rollout failed. Current status:"
  kubectl describe deployment my-app
  kubectl rollout undo deployment/my-app
  kubectl rollout status deployment/my-app --timeout=120s
  exit 1
fi

Timeout Configuration

Always set a timeout in automated environments:

# 5-minute timeout
kubectl rollout status deployment/my-app --timeout=300s

# 10-minute timeout for large deployments
kubectl rollout status deployment/my-app --timeout=600s

# Quick check without watching
kubectl rollout status deployment/my-app --watch=false

Without --timeout, the command waits indefinitely. If the rollout is stuck due to image pull errors, failing readiness probes, or resource constraints, your pipeline will hang.

Understanding Rollout States

A rollout progresses through several states:

# In progress
# Waiting for deployment "my-app" rollout to finish: 1 of 3 updated replicas are available...

# Complete
# deployment "my-app" successfully rolled out

# Stalled (progressDeadlineSeconds exceeded)
# error: deployment "my-app" exceeded its progress deadline

The progress deadline (default 600 seconds) determines how long Kubernetes waits for the rollout to make progress before marking it as failed. You can configure this in the deployment spec:

spec:
  progressDeadlineSeconds: 300

Combining with Other Commands

Use rollout status as part of a broader monitoring workflow:

# Apply, watch, and verify
kubectl apply -f deployment.yaml
kubectl rollout status deployment/my-app --timeout=300s

# Check the resulting pods
kubectl get pods -l app=my-app

# Verify the new image is running
kubectl get deployment my-app -o jsonpath='{.spec.template.spec.containers[0].image}'

Debugging Failed Rollouts

When rollout status reports a failure, investigate:

# Check deployment conditions
kubectl describe deployment my-app | grep -A 10 "Conditions"

# Check for pod issues
kubectl get pods -l app=my-app
kubectl describe pod <failing-pod-name>

# Check events
kubectl get events --sort-by=.lastTimestamp -n <namespace>

# Check the latest ReplicaSet
kubectl get rs -l app=my-app --sort-by=.metadata.creationTimestamp
kubectl describe rs <latest-replicaset>

Best Practices

Always use --timeout in scripts and CI/CD pipelines. Monitor rollout status after any change that triggers a rollout (apply, set image, patch, edit). Pair rollout status with rollout undo for automated rollback on failure. Set appropriate progressDeadlineSeconds in your deployment spec to match your application's startup time.