Skip to content

wait_for

Collection Note

This module is part of the ansible.builtin collection. To install the collection, use:

ansible-galaxy collection install ansible.builtin
Added in version 0.7.

Synopsis

  • You can wait for a set amount of time O(timeout), this is the default if nothing is specified or just O(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 M(community.libvirt.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 M(ansible.windows.win_wait_for) module instead.

Parameters

Parameter Defaults / Choices Comments
active_connection_states
list / elements=str		 Default: ['ESTABLISHED', 'FIN_WAIT1', 'FIN_WAIT2', 'SYN_RECV', 'SYN_SENT', 'TIME_WAIT']
 The list of TCP connection states which are counted as active connections.
Version Added: 2.3
connect_timeout
int		 Default: 5
 Maximum number of seconds to wait for a connection to happen before closing and retrying.
delay
int		 Number of seconds to wait before starting to poll.
exclude_hosts
list / elements=str		 List of hosts or IPs to ignore when looking for active TCP connections for V(drained) state.
Version Added: 1.8
host
str		 Default: 127.0.0.1
 A resolvable hostname or IP address to wait for.
msg
str		 This overrides the normal error message from a failure to meet the required conditions.
Version Added: 2.4
path
path		 Path to a file on the filesystem that must exist before continuing.
O(path) and O(port) are mutually exclusive parameters.
Version Added: 1.4
port
int		 Port number to poll.
O(path) and O(port) are mutually exclusive parameters.
search_regex
str		 Can be used to match a string in either a file or a socket connection.
Defaults to a multiline regex.
Version Added: 1.4
sleep
int		 Default: 1
 Number of seconds to sleep between checks.
Before Ansible 2.3 this was hardcoded to 1 second.
Version Added: 2.3
state
str		 Default: started
Choices: absent, drained, present, started, stopped		 Either V(present), V(started), or V(stopped), V(absent), or V(drained).
When checking a port V(started) will ensure the port is open, V(stopped) will check that it is closed, V(drained) will check for active connections.
When checking for a file or a search string V(present) or V(started) will ensure that the file or string is present before continuing, V(absent) will check that file is absent or removed.
timeout
int		 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.

Examples

- name: Sleep for 300 seconds and continue with play
  ansible.builtin.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
  ansible.builtin.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
  ansible.builtin.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
  ansible.builtin.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
  ansible.builtin.wait_for:
    path: /tmp/foo

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

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

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

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

- name: Output customized message when failed
  ansible.builtin.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"
  ansible.builtin.wait_for:
    port: 22
    host: '{{ (ansible_ssh_host|default(ansible_host))|default(inventory_hostname) }}'
    search_regex: OpenSSH
    delay: 10
    timeout: 300
  delegate_to: localhost

# Same as above but using config lookup for the target,
# most plugins use 'remote_addr', but ssh uses 'host'
- name: Wait 300 seconds for port 22 to become open and contain "OpenSSH"
  ansible.builtin.wait_for:
    port: 22
    host: "{{ lookup('config', 'host', plugin_name='ssh', plugin_type='connection') }}"
    search_regex: OpenSSH
    delay: 10
    timeout: 300
  delegate_to: localhost

Return Values

Key Data Type Description Returned
elapsed int The number of seconds that elapsed while waiting always
match_groupdict dict Dictionary containing all the named subgroups of the match, keyed by the subgroup name, as returned by U(https://docs.python.org/3/library/re.html#re.MatchObject.groupdict) always
match_groups list Tuple containing all the subgroups of the match as returned by U(https://docs.python.org/3/library/re.html#re.MatchObject.groups) always

Authors

  • Jeroen Hoekx (@jhoekx)
  • John Jarvis (@jarv)
  • Andrii Radyk (@anderender)