wait_for – Waits for a condition before continuing — Ansible Documentation

- AnsibleFest
- Products
- Community
- Webinars & Training
- Blog

Documentation

# wait_for – Waits for a condition before continuing

- Synopsis
- Parameters
- Notes
- See Also
- Examples
- Return Values
- Status

## Synopsis

- You can wait for a set amount of time `timeout`, this is the default if nothing is specified or just `timeout` is specified. This does not produce an error.
- Waiting for a port to become available is useful for when services are not immediately available after their init scripts return which is true of certain Java application servers.
- It is also useful when starting guests with the virt module and needing to pause until they are ready.
- This module can also be used to wait for a regex match a string to be present in a file.
- In Ansible 1.6 and later, this module can also be used to wait for a file to be available or absent on the filesystem.
- In Ansible 1.8 and later, this module can also be used to wait for active connections to be closed before continuing, useful if a node is being rotated out of a load balancer pool.
- For Windows targets, use the win_wait_for module instead.

## Parameters

Parameter | Choices/Defaults | Comments
--- | --- | ---
active_connection_states list | Default: ["ESTABLISHED", "FIN_WAIT1", "FIN_WAIT2", "SYN_RECV", "SYN_SENT", "TIME_WAIT"] | The list of TCP connection states which are counted as active connections.
connect_timeout integer | Default: 5 | Maximum number of seconds to wait for a connection to happen before closing and retrying.
delay integer | Default: 0 | Number of seconds to wait before starting to poll.
exclude_hosts list |  | List of hosts or IPs to ignore when looking for active TCP connections for `drained` state.
host string | Default: "127.0.0.1" | A resolvable hostname or IP address to wait for.
msg string added in 2.4 |  | This overrides the normal error message from a failure to meet the required conditions.
path path |  | Path to a file on the filesystem that must exist before continuing. `path` and `port` are mutually exclusive parameters.
port integer |  | Port number to poll. `path` and `port` are mutually exclusive parameters.
search_regex string |  | Can be used to match a string in either a file or a socket connection. Defaults to a multiline regex.
sleep integer | Default: 1 | Number of seconds to sleep between checks. Before Ansible 2.3 this was hardcoded to 1 second.
state string | Choices: absent drained present started ← stopped | Either `present`, `started`, or `stopped`, `absent`, or `drained`. When checking a port `started` will ensure the port is open, `stopped` will check that it is closed, `drained` will check for active connections. When checking for a file or a search string `present` or `started` will ensure that the file or string is present before continuing, `absent` will check that file is absent or removed.
timeout integer | Default: 300 | Maximum number of seconds to wait for, when used with another condition it will force an error. When used without other conditions it is equivalent of just sleeping.

## Notes

Note

- The ability to use search_regex with a port connection was added in Ansible 1.7.
- Prior to Ansible 2.4, testing for the absence of a directory or UNIX socket did not work correctly.
- Prior to Ansible 2.4, testing for the presence of a file did not work correctly if the remote user did not have read access to that file.
- Under some circumstances when using mandatory access control, a path may always be treated as being absent even if it exists, but can’t be modified or created by the remote user either.
- When waiting for a path, symbolic links will be followed. Many other modules that manipulate files do not follow symbolic links, so operations on the path using other modules may not work exactly as expected.

## See Also

See also

wait_for_connection – Waits until remote system is reachable/usable
  The official documentation on the wait_for_connection module.
win_wait_for – Waits for a condition before continuing
  The official documentation on the win_wait_for module.
win_wait_for_process – Waits for a process to exist or not exist before continuing
  The official documentation on the win_wait_for_process module.

## Examples

    - name: sleep for 300 seconds and continue with play
      wait_for:
        timeout: 300
      delegate_to: localhost

    - name: Wait for port 8000 to become open on the host, don't start checking for 10 seconds
      wait_for:
        port: 8000
        delay: 10

    - name: Waits for port 8000 of any IP to close active connections, don't start checking for 10 seconds
      wait_for:
        host: 0.0.0.0
        port: 8000
        delay: 10
        state: drained

    - name: Wait for port 8000 of any IP to close active connections, ignoring connections for specified hosts
      wait_for:
        host: 0.0.0.0
        port: 8000
        state: drained
        exclude_hosts: 10.2.1.2,10.2.1.3

    - name: Wait until the file /tmp/foo is present before continuing
      wait_for:
        path: /tmp/foo

    - name: Wait until the string "completed" is in the file /tmp/foo before continuing
      wait_for:
        path: /tmp/foo
        search_regex: completed

    - name: Wait until regex pattern matches in the file /tmp/foo and print the matched group
      wait_for:
        path: /tmp/foo
        search_regex: completed (?P<task>\w+)
      register: waitfor
    - debug:
        msg: Completed {{ waitfor['groupdict']['task'] }}

    - name: Wait until the lock file is removed
      wait_for:
        path: /var/lock/file.lock
        state: absent

    - name: Wait until the process is finished and pid was destroyed
      wait_for:
        path: /proc/3466/status
        state: absent

    - name: Output customized message when failed
      wait_for:
        path: /tmp/foo
        state: present
        msg: Timeout to find file /tmp/foo

    # Do not assume the inventory_hostname is resolvable and delay 10 seconds at start
    - name: Wait 300 seconds for port 22 to become open and contain "OpenSSH"
      wait_for:
        port: 22
        host: '{{ (ansible_ssh_host|default(ansible_host))|default(inventory_hostname) }}'
        search_regex: OpenSSH
        delay: 10
      connection: local

    # Same as above but you normally have ansible_connection set in inventory, which overrides 'connection'
    - name: Wait 300 seconds for port 22 to become open and contain "OpenSSH"
      wait_for:
        port: 22
        host: '{{ (ansible_ssh_host|default(ansible_host))|default(inventory_hostname) }}'
        search_regex: OpenSSH
        delay: 10
      vars:
        ansible_connection: local

## Return Values

Common return values are documented here, the following are the fields unique to this module:

Key | Returned | Description
--- | --- | ---
elapsed integer | always | The number of seconds that elapsed while waiting Sample: 23
match_groupdict dictionary | always | Dictionary containing all the named subgroups of the match, keyed by the subgroup name, as returned by https://docs.python.org/2/library/re.html#re.MatchObject.groupdict Sample: {'group': 'match'}
match_groups list | always | Tuple containing all the subgroups of the match as returned by https://docs.python.org/2/library/re.html#re.MatchObject.groups Sample: ['match 1', 'match 2']

## Status

- This module is guaranteed to have backward compatible interface changes going forward. [stableinterface]
- This module is maintained by the Ansible Core Team. [core]

### Red Hat Support

More information about Red Hat’s support of this module is available from this Red Hat Knowledge Base article.

### Authors

- Jeroen Hoekx (@jhoekx)
- John Jarvis (@jarv)
- Andrii Radyk (@AnderEnder)

Hint

If you notice any issues in this documentation, you can edit this document to improve it.