kubectl-wait

Wait for a deployment to become available

$ kubectl wait --for=condition=available deployment/[deployment_name]

$ kubectl wait --for=condition=ready pod [[-l|--selector]] [label_key]=[label_value]

$ kubectl wait --for=delete pod [pod_name]

$ kubectl wait --for=condition=complete job/[job_name] --timeout 120s

kubectl wait (TYPE NAME | TYPE/NAME | TYPE --all | TYPE -l key=value | -f FILENAME) --for={delete|condition=NAME[=VALUE]|jsonpath='EXPR'} [--timeout=DURATION] [options]

TYPE NAME | TYPE/NAME
    Specifies the kind of resource and its name (e.g., pod my-pod or deployment/nginx-deployment) to wait on.

TYPE --all
    Waits for all resources of the specified TYPE within the current namespace.

TYPE -l key=value
    Waits for resources of the specified TYPE that match the given label selector (e.g., pod -l app=nginx).

--for=delete
    Waits for the specified resource(s) to be completely deleted from the cluster.

--for=condition=<condition-name>[=<condition-value>]
    Waits for a specific <condition-name> on the resource(s) to become true. Optionally, a <condition-value> (e.g., True, False, Unknown) can be specified; defaults to True.

--for=jsonpath='<jsonpath-expression>'
    Waits until the provided JSON path expression evaluates to a non-empty, non-false value within the resource's status.

--timeout=duration
    The maximum time to wait for the condition to be met (e.g., 5m for 5 minutes, 30s for 30 seconds). A value of 0 indicates no timeout.

-f, --filename strings
    Specifies one or more filenames, directories, or URLs containing resource definitions to wait for.

-A, --all-namespaces
    If present, waits for resources across all namespaces. Only applicable when using selectors or when waiting for all resources of a type.

-n, --namespace string
    If present, the namespace scope for this CLI request. Overrides the default namespace.

-l, --selector string
    Selector (label query) to filter on. Supports '=', '==', and '!='.

kubectl wait is a powerful command-line utility for Kubernetes that allows users to block execution until one or more specified resources reach a desired state or condition. It's an essential tool for scripting, automation, and CI/CD pipelines, ensuring that subsequent operations only proceed once a resource is fully ready, available, or deleted. Instead of manual polling or complex scripting logic, kubectl wait provides a native and reliable mechanism to monitor resource conditions like Ready, Complete, Available, or Deleted. The command continuously polls the Kubernetes API server until the specified condition evaluates to true or a defined timeout duration is reached. It supports waiting for various resource types, identified by name, label selectors, or even from manifest files. This capability simplifies the orchestration of complex deployments, ensuring dependencies are met before progressing to the next step in a workflow.

kubectl wait polls the API server periodically. Frequent use on many resources or with very short polling intervals (which are not directly configurable) can put a light load on the API server.
It provides a timeout mechanism but doesn't inherently offer detailed debugging information about why a condition wasn't met, beyond simply timing out.
For complex, inter-resource dependencies, it might be necessary to chain multiple kubectl wait commands or use more advanced orchestration tools.

The exact polling interval for kubectl wait is not directly configurable by the user and is typically hardcoded within kubectl (often a few seconds, e.g., 1 second). This means users cannot fine-tune the frequency of API server queries.

kubectl wait can be used with virtually any Kubernetes resource type, including built-in resources like Pods, Deployments, Services, and also Custom Resources (CRs), as long as they expose conditions or can be tracked for deletion.

kubectl wait was introduced in Kubernetes to provide a more robust and declarative way for scripts and automation to synchronize with the state of Kubernetes resources. Prior to its inclusion, users often relied on less reliable methods like `kubectl get -w` (watch mode) combined with `grep` or custom polling loops in shell scripts. Its development aimed to streamline CI/CD pipelines and operator patterns by offering a native, idempotent, and timeout-aware mechanism for waiting on resource conditions, thereby improving the reliability and readability of Kubernetes automation scripts.

kubectl get(1), kubectl apply(1), kubectl delete(1), kubectl rollout(1)