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

> kubectl wait blocks until a resource reaches a condition, the way a pipeline gates a deploy. Reference for --for=condition, --timeout, selectors, and the timed-out error.

Source: https://latchkey.dev/learn/command-reference/kubectl-wait-for-condition-ready  
Updated: 2026-06-30

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
```

> Always set `--request-timeout` in CI. Without it an unreachable API server hangs until the job times out, which turns a thirty-second failure into a twenty-minute one.

## FAQ

### 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,

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt