kubectl rollout status: Block Until a Deploy Finishes

By Daniel Zoghalchali·Latchkey

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

Frequently asked questions

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.