# kubectl rollout status: Block Until a Deploy Finishes

> kubectl rollout status blocks until a Deployment, StatefulSet, or DaemonSet finishes rolling out. Reference for --timeout, --watch, and the deadline-exceeded error.

Source: https://latchkey.dev/learn/command-reference/kubectl-rollout-status-watch  
Updated: 2026-06-30

kubectl rollout status watches a workload until its rollout completes and exits 0, or exits non-zero if the rollout stalls past the timeout.

This is the standard way to make a deploy step wait for the new pods to come up before the job reports success.

## What it does

kubectl rollout status follows the progress of a Deployment, StatefulSet, or DaemonSet rollout, printing lines like "Waiting for deployment ... 2 of 3 updated replicas are available" and returning 0 when all updated replicas are available. With `--watch=false` it reports the current status once and returns.

## Common usage

```Terminal
kubectl rollout status deployment/api --timeout=180s
kubectl rollout status statefulset/db -n data --timeout=300s
# one-shot status, no blocking
kubectl rollout status deploy/api --watch=false
```

## Options

| Flag | What it does |
| --- | --- |
| --timeout=<dur> | Fail if the rollout is not complete within this duration |
| --watch | Watch until complete (default true) |
| --revision=<n> | Wait for a specific revision to roll out |
| -n, --namespace | Namespace of the workload |

## In CI

Pair `kubectl apply` with `kubectl rollout status --timeout` so a stuck rollout fails the pipeline instead of hanging. Set the timeout slightly above the Deployment `progressDeadlineSeconds`, otherwise the rollout may still be reported in-progress when your job already gave up.

## Common errors in CI

"error: deployment ... exceeded its progress deadline" means the new ReplicaSet never became available within `progressDeadlineSeconds`; the underlying pods are usually in ImagePullBackOff or failing readiness. "error: timed out waiting for the condition" comes from `--timeout` firing first. "error: no rollout status for resources of type Pod" means you pointed it at a Pod; rollout status only applies to Deployment, StatefulSet, and DaemonSet.

## 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 status: Block Until a Deploy Finishes?

This is the standard way to make a deploy step wait for the new pods to come up before the job reports success.

### What it does?

kubectl rollout status follows the progress of a Deployment, StatefulSet, or DaemonSet rollout, printing lines like "Waiting for deployment ... 2 of 3 updated replicas are available" and returning 0 when all updated replicas are available. With --watch=false it reports the current status once and returns.

### In CI?

Pair kubectl apply with kubectl rollout status --timeout so a stuck rollout fails the pipeline instead of hanging. Set the timeout slightly above the Deployment progressDeadlineSeconds, otherwise the rollout may still be reported in-progress when your job already gave up.

### Common errors in CI?

"error: deployment ... exceeded its progress deadline" means the new ReplicaSet never became available within progressDeadlineSeconds; the underlying pods are usually in ImagePullBackOff or failing readiness. "error: timed out waiting for the condition" comes from --timeout firing first.

---

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