wait_for – Waits for a condition before continuing¶
Synopsis¶
- You can wait for a set amount of time
timeout, this is the default if nothing is specified or justtimeoutis 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¶
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.