kubectl wait

When to Use kubectl wait

kubectl wait blocks execution until a Kubernetes resource reaches a specific condition or is deleted. It is essential in scripts, CI/CD pipelines, and any automation where you need to synchronize with cluster state.

Condition-Based Waiting

The most common use is waiting for a condition to become true:

# Wait for a pod to be ready
kubectl wait --for=condition=Ready pod/my-app --timeout=120s
# pod/my-app condition met

# Wait for a deployment to be available
kubectl wait --for=condition=Available deployment/my-app --timeout=300s

# Wait for a node to be ready
kubectl wait --for=condition=Ready node/worker-1 --timeout=600s

# Wait for a job to complete
kubectl wait --for=condition=Complete job/data-migration --timeout=1800s

Waiting for Deletion

Wait for a resource to be fully removed:

# Delete and wait for removal
kubectl delete pod/my-app
kubectl wait --for=delete pod/my-app --timeout=60s

# Useful for ensuring finalizers complete
kubectl delete pvc/data-volume
kubectl wait --for=delete pvc/data-volume --timeout=300s

JSONPath Conditions

For custom conditions not represented by standard status conditions, use jsonpath:

# Wait for a specific field value
kubectl wait --for=jsonpath='{.status.phase}'=Running pod/my-app --timeout=60s

# Wait for a specific number of ready replicas
kubectl wait --for=jsonpath='{.status.readyReplicas}'=3 deployment/my-app --timeout=120s

Label Selector Waiting

Wait for multiple resources matching a selector:

# Wait for all pods with a label to be ready
kubectl wait --for=condition=Ready pods -l app=nginx --timeout=120s

# Wait for all pods in a deployment to be ready
kubectl wait --for=condition=Ready pods -l app=my-app,version=v2 --timeout=180s

# Wait for all pods in a namespace
kubectl wait --for=condition=Ready pods --all -n staging --timeout=300s

CI/CD Pipeline Patterns

A deployment pipeline using wait:

#!/bin/bash
set -e

# Apply manifests
kubectl apply -f manifests/

# Wait for deployment
kubectl wait --for=condition=Available deployment/api-server -n production --timeout=300s

# Wait for dependent services
kubectl wait --for=condition=Available deployment/worker -n production --timeout=300s
kubectl wait --for=condition=Ready pods -l app=cache -n production --timeout=120s

echo "Deployment complete and healthy."

Timeout Behavior

When the timeout expires before the condition is met, kubectl exits with code 1:

kubectl wait --for=condition=Ready pod/slow-starter --timeout=10s
# error: timed out waiting for the condition on pods/slow-starter

echo $?
# 1

Set timeout to 0 to wait indefinitely (use with caution):

kubectl wait --for=condition=Ready pod/my-app --timeout=0

Combining with Other Commands

# Apply and wait
kubectl apply -f deployment.yaml && \
kubectl wait --for=condition=Available deployment/my-app --timeout=300s && \
echo "Ready for traffic"

# Scale and wait
kubectl scale deployment/my-app --replicas=5
kubectl wait --for=jsonpath='{.status.readyReplicas}'=5 deployment/my-app --timeout=180s

# Drain and wait for node to be unused
kubectl drain worker-1 --ignore-daemonsets
kubectl wait --for=delete pods --field-selector=spec.nodeName=worker-1 --timeout=300s

Common Conditions by Resource Type

| Resource | Condition | Meaning | |----------|-----------|---------| | Pod | Ready | All containers passed readiness probes | | Pod | PodScheduled | Pod has been assigned to a node | | Pod | Initialized | All init containers completed | | Deployment | Available | MinReadySeconds passed for enough replicas | | Deployment | Progressing | Rollout is making progress | | Job | Complete | Job finished successfully | | Job | Failed | Job has failed | | Node | Ready | Node is healthy and accepting pods | | PVC | Bound | PersistentVolumeClaim is bound to a PV |

Error Handling

Robust scripts should handle wait failures:

if ! kubectl wait --for=condition=Available deployment/my-app --timeout=300s; then
  echo "Deployment failed to become available"
  kubectl rollout status deployment/my-app
  kubectl describe deployment/my-app
  kubectl get pods -l app=my-app
  exit 1
fi

This pattern ensures you get diagnostic information when a wait fails, rather than just an opaque timeout error.