kubectl wait --for=condition: Gate CI on Readiness

By Kaveh Alemi·Latchkey

kubectl wait blocks until the named resources satisfy a condition (or jsonpath) and exits non-zero if the timeout passes first.

A deploy step should not return until the workload is actually ready. kubectl wait turns a Kubernetes condition into an exit code you can gate on.

What it does

kubectl wait watches one or more resources and blocks until they meet --for=condition=<Name> (or --for=delete, or a jsonpath match), then exits 0. If --timeout elapses first it exits 1 with a timed-out message, so a CI job fails cleanly instead of proceeding against a half-ready cluster.

Common usage

Terminal

kubectl wait --for=condition=Ready pod -l app=api --timeout=120s
kubectl wait --for=condition=Available deploy/api --timeout=180s
kubectl wait --for=delete pod/migrate --timeout=60s
# wait on a jsonpath value (kubectl 1.23+)
kubectl wait --for=jsonpath='{.status.phase}'=Running pod/api

Options

Flag	What it does
--for=condition=<Name>	Wait for a status condition such as Ready or Available
--for=delete	Wait until the resource is deleted
--for=jsonpath='{path}'=<v>	Wait until a jsonpath field equals a value (1.23+)
--timeout=<dur>	Give up after this duration (e.g. 120s, 5m); 0 means do not wait
-l, --selector	Match resources by label instead of name
--all	Select all resources of the type in the namespace

In CI

Always pass an explicit --timeout; the default of 30s is often too short for image pulls. Waiting on a Deployment for condition=Available confirms the rollout, but for a fresh Deployment that has never reconciled, kubectl rollout status is more reliable than wait.

Common errors in CI

"error: timed out waiting for the condition" means the resource never reached the condition inside --timeout; describe it to find the real cause (ImagePullBackOff, failing probes). "error: no matching resources found" means the selector matched nothing yet, common when you wait before the controller has created the pods; create first, then wait. A condition name typo like condition=ready (lowercase) silently never matches.

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 wait --for=condition: Gate CI on Readiness?

A deploy step should not return until the workload is actually ready. kubectl wait turns a Kubernetes condition into an exit code you can gate on.

What it does?

kubectl wait watches one or more resources and blocks until they meet --for=condition=<Name> (or --for=delete, or a jsonpath match), then exits 0. If --timeout elapses first it exits 1 with a timed-out message, so a CI job fails cleanly instead of proceeding against a half-ready cluster.

In CI?

Always pass an explicit --timeout; the default of 30s is often too short for image pulls. Waiting on a Deployment for condition=Available confirms the rollout, but for a fresh Deployment that has never reconciled, kubectl rollout status is more reliable than wait.

Common errors in CI?

"error: timed out waiting for the condition" means the resource never reached the condition inside --timeout; describe it to find the real cause (ImagePullBackOff, failing probes). "error: no matching resources found" means the selector matched nothing yet, common when you wait before the controller has created the pods; create first,