kubectl wait: Usage, Options & Common CI Errors

Make the pipeline pause until a resource is actually ready.

kubectl wait blocks until objects satisfy a condition (or a timeout fires), returning non-zero on timeout. It replaces fragile sleep/poll loops with a precise, fail-fast gate.

What it does

kubectl wait --for=condition=Ready pod/X blocks until the named condition is true on the matched objects. --for=delete waits for deletion; --for=jsonpath='{.status...}'=value waits on an arbitrary field. -l selects many objects and --timeout bounds the wait. A timeout exits 1, so the pipeline fails deterministically.

Common usage

kubectl wait --for=condition=Ready pod -l app=web --timeout=120s
kubectl wait --for=condition=Available deploy/web --timeout=5m
kubectl wait --for=delete pod/old --timeout=60s
kubectl wait --for=jsonpath='{.status.phase}'=Succeeded job/migrate

Common errors in CI

"error: timed out waiting for the condition" is wait doing its job - the resource never reached the state. Pair it with kubectl describe and logs to learn why (failing probe, crash, image pull). A subtler failure: "error: no matching resources found" if you wait before the object is even created. Wait does not retry creation, so create/apply first, then wait. And "condition X is not found" / waiting on a condition the resource type does not have (e.g. condition=Ready on a Deployment instead of Available) just times out; match the condition to the kind.

Related guides