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.
"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.
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: Usage, Options & Common CI Errors?
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 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.
