wait_for
wait_for waits, from the node, until something is ready: a TCP port, a
path, an HTTP response, or a command that only the program itself can
answer. It is the normal node task for a node task block's verify phase
after a service is started or reloaded. It changes nothing and reports
unchanged when ready.
Three more forms wait for the health that Docker or Podman reports of a
container or of a Docker Compose project: docker_container_is_healthy,
docker_compose_project_is_ready, and podman_container_is_healthy. The
pages docker_compose_project and
podman_quadlet describe them.
Use http when a later node task reads one response, and
assert to check a value once.
Inputs
tcp_port_accepts_connections(integer; optional): TCP port from 1 to 65535; ready when a connection succeeds; exactly one readiness form is requiredtcp_port_refuses_connections(integer; optional): TCP port from 1 to 65535; ready when a connection is refused; a lookup failure or timeout does not counttcp_host(string; default127.0.0.1): only with tcp_port_accepts_connections or tcp_port_refuses_connections; a machine the node can reachpath_exists(string; optional): absolute path; ready when the path existspath_is_missing(string; optional): absolute path; ready when the path is missingurl_responds(string; optional): HTTP or HTTPS; read-only GET, no redirects; 10-second request limit bounded by the remaining waitcommand_succeeds(string; optional): a read-only command run with bash -c; exit code 0 means ready, any other code means not yet; also runs once during dryruntrusted_certificate_authority_file(string; optional): only with url_responds; absolute path on the node of a certificate authority's certificate, or a self-signed certificate, to trustdangerously_skip_server_certificate_check(boolean; defaultfalse): only with url_responds; true removes verification of the HTTPS server's identity; prefer trusted_certificate_authority_file for a private authorityrun_as_user_account(string; defaultroot): only with command_succeeds; as on shellrun_from_directory(string; default/): only with command_succeeds; as on shellenv(mapping; optional): only with command_succeeds; environment variables, as on shelldocker_container_is_healthy(string; optional): the name of a Docker container; ready when Docker reports it healthy by the container's own health check; a container that declares no health check fails the task at once; one form of wait_for, instead of another readiness formdocker_compose_project_is_ready(string; optional): absolute path of a Docker Compose project directory. Ready when every container with a health check is healthy and every container without a health check is running or has completed. Completed means the container exited with code 0 and the restart policy does not start the container again, as for a service that runs once. Choose docker_compose_project_is_ready instead of another readiness formpodman_container_is_healthy(string; optional): the name of a Podman container (ContainerName= in its Quadlet file); ready when Podman reports it healthy by the container's own health check (HealthCmd=); a container that declares no health check fails the task at once; one form of wait_for, instead of another readiness formpodman_container_of_user_account(string; optional): only with podman_container_is_healthy: the account other than root whose container it is; without it, the container is the system's (root's)expected_http_status_codes(list of integers; default[200]): the list of accepted HTTP status codes; only with url_respondsresponse_body_contains(string; optional): optional; plain text (not a pattern) the response body must contain; references resolve; only with url_respondswait_at_most(string; default60s): positive duration for the whole wait; checks repeat every second
Outputs
The node task's result holds these fields. A later node task reads them as .node_tasks.<id>.<field>, where <id> is the node task's id.
statuschangereasonhttp_status_coderesponse_bodyresponse_body_jsonexit_codestdoutstderr
What a dryrun reports
Checks once without waiting; reports not_checked when not ready; always unchanged.
Retries and time limits
Runs once; rejects retry, time_limit, and time_limit_per_try, and ignores node_task_defaults; wait_at_most bounds the wait.
Examples
Wait for a port
- wait_for:
tcp_port_accepts_connections: 5432
wait_at_most: 60s
The node checks every second whether something accepts TCP connections on its own port 5432, for up to 60 seconds.
Wait for a path
- wait_for:
path_exists: /run/app/ready
wait_at_most: 30s
Wait for an HTTP response with an expected body
- wait_for:
url_responds: http://127.0.0.1:8080/health
expected_http_status_codes: [200]
response_body_contains: ready
wait_at_most: 30s
Wait for a command
Only the program itself can say that it is ready:
- wait_for:
command_succeeds: kubectl get --raw /readyz
run_as_user_account: kube
env:
KUBECONFIG: /etc/rancher/k3s/k3s.yaml
wait_at_most: 120s
How it works
Choose exactly one form. Each check runs from the node:
| Check | When ready | Related settings |
|---|---|---|
tcp_port_accepts_connections |
A TCP connection succeeds. | tcp_host defaults to 127.0.0.1, the node itself. |
tcp_port_refuses_connections |
A TCP connection is refused. A lookup failure or timeout does not count. | Only tcp_port_accepts_connections and tcp_port_refuses_connections accept tcp_host. |
path_exists |
The absolute path exists. | |
path_is_missing |
The absolute path does not exist. | |
url_responds |
A GET returns an accepted HTTP status, and any required body text. | expected_http_status_codes defaults to [200]; response_body_contains is literal text. |
command_succeeds |
The command exits with code 0. | Runs as root from /; run_as_user_account, run_from_directory, and env work as on shell. |
A container form cannot be combined with tcp_port_accepts_connections,
tcp_port_refuses_connections, path_exists, path_is_missing,
url_responds, or command_succeeds. Choose at most one of
docker_container_is_healthy, docker_compose_project_is_ready, and
podman_container_is_healthy.
The name docker_compose_project_is_ready includes containers without health
checks: those containers must run or have completed successfully.
- The wait.
wait_forchecks every second for up towait_at_most, which defaults to60sand limits the whole wait. No request can outlast the remaining wait. - A URL check sends a
GET: HTTP or HTTPS, no redirects, a 10-second request timeout bounded by the remaining wait, and a response body of up to 1 MiB.expected_http_status_codesandresponse_body_containsare allowed only withurl_responds. The last response supplieshttp_status_code,response_body, andresponse_body_jsonin the result. - HTTPS certificates. Certificate checks are on by default. For a private
authority or a self-signed certificate, name the certificate on the node in
trusted_certificate_authority_file. To remove server identity verification, explicitly writedangerously_skip_server_certificate_check: true; see protective choices. - A script check runs the command with the shell rules. The script must
only read: MMX runs it again every second, and once during dryrun. When the
wait ends without readiness, the failure shows the exit code and output of
the last check, and the result has them as
exit_code,stdout, andstderr. - When time runs out,
wait_forfails with the last observation, such as the last HTTP status code or connection error: what the last check that finished saw. A check that was still running when the wait ended says only that it was interrupted, so its interruption is not the observation. - Dryrun checks once without waiting. If the condition is not met,
wait_forreportsnot_checked. Earlier node tasks in a real run may make the condition ready. - Where
wait_foris allowed. In ordinary node task lists and in a node task block'sverify,activate,checks_before_restart_or_reload,on_failure, andcleanup. - Retries and time limits. Like
reboot,wait_forrejectsretry,time_limit, andtime_limit_per_tryat the node task level, ignoresnode_task_defaults, and uses its ownwait_at_mostas the only wait limit.
Errors and what they mean
- The wait ends without readiness. The task fails with the last
observation. For a script, the failure holds the last exit code and
output; for a URL, the last HTTP status code or connection error. Check
the service on the node, or give a slow start a longer
wait_at_most. retry,time_limit, ortime_limit_per_tryon await_fortask. Validation rejects node task settingsretry,time_limit, andtime_limit_per_try. Usewait_at_most.- More than one readiness form, or
tcp_hostwithout a TCP form. Validation rejects the task. Choose exactly one readiness form, from the table or the container forms above, and use only the form's related settings.
Tested on
Distributions: Debian 12 and 13, Ubuntu 24.04 and 26.04, Arch Linux, openSUSE Leap 16.1, Rocky Linux 9, AlmaLinux 10, Fedora 45.
The base suite covers this module (vm.py test, http_requests.py, account_units.py) and runs on every tested distribution.
The suite account_units.py covers wait_for with command_succeeds. Many other
suites wait with wait_for for the service they start, and the whole
catalog runs them on Debian 12 and 13 and Ubuntu 24.04 and 26.04 (validation
record).
Why it works this way
- Waiting is a module, not a shell loop. Keeping waiting in
wait_formakes the readiness condition and its limit visible without a shell script. - A dryrun reports
not_checkedinstead of failing. Earlier node tasks in a real run may make the condition ready. - Each form names the whole condition. A reader can see whether a port must accept or refuse connections, or a path must exist or disappear, without interpreting a separate state. Compose readiness does not require every container to declare a health check.
- Certificate checks stay on by default. A private CA file keeps server identity verification; the explicit dangerous choice removes that check.
This page is docs/reference/modules/wait_for.md in the MMX repository.