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 required
  • tcp_port_refuses_connections (integer; optional): TCP port from 1 to 65535; ready when a connection is refused; a lookup failure or timeout does not count
  • tcp_host (string; default 127.0.0.1): only with tcp_port_accepts_connections or tcp_port_refuses_connections; a machine the node can reach
  • path_exists (string; optional): absolute path; ready when the path exists
  • path_is_missing (string; optional): absolute path; ready when the path is missing
  • url_responds (string; optional): HTTP or HTTPS; read-only GET, no redirects; 10-second request limit bounded by the remaining wait
  • command_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 dryrun
  • trusted_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 trust
  • dangerously_skip_server_certificate_check (boolean; default false): only with url_responds; true removes verification of the HTTPS server's identity; prefer trusted_certificate_authority_file for a private authority
  • run_as_user_account (string; default root): only with command_succeeds; as on shell
  • run_from_directory (string; default /): only with command_succeeds; as on shell
  • env (mapping; optional): only with command_succeeds; environment variables, as on shell
  • docker_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 form
  • docker_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 form
  • podman_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 form
  • podman_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_responds
  • response_body_contains (string; optional): optional; plain text (not a pattern) the response body must contain; references resolve; only with url_responds
  • wait_at_most (string; default 60s): 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.

  • status
  • change
  • reason
  • http_status_code
  • response_body
  • response_body_json
  • exit_code
  • stdout
  • stderr

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_for checks every second for up to wait_at_most, which defaults to 60s and 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_codes and response_body_contains are allowed only with url_responds. The last response supplies http_status_code, response_body, and response_body_json in 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 write dangerously_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, and stderr.
  • When time runs out, wait_for fails 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_for reports not_checked. Earlier node tasks in a real run may make the condition ready.
  • Where wait_for is allowed. In ordinary node task lists and in a node task block's verify, activate, checks_before_restart_or_reload, on_failure, and cleanup.
  • Retries and time limits. Like reboot, wait_for rejects retry, time_limit, and time_limit_per_try at the node task level, ignores node_task_defaults, and uses its own wait_at_most as 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, or time_limit_per_try on a wait_for task. Validation rejects node task settings retry, time_limit, and time_limit_per_try. Use wait_at_most.
  • More than one readiness form, or tcp_host without 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_for makes the readiness condition and its limit visible without a shell script.
  • A dryrun reports not_checked instead 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.