kubectl wait --for=condition: Gate CI on Readiness
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
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/apiOptions
| 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.