Try SpotterWaits for a condition before continuing
| "added in version" 0.7 of ansible.builtin"
Authors: Jeroen Hoekx (@jhoekx), John Jarvis (@jarv), Andrii Radyk (@AnderEnder)
pipInstall with pip install ansible-core==2.16.5
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.
- 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
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"
ansible.builtin.wait_for:
port: 22
host: '{{ (ansible_ssh_host|default(ansible_host))|default(inventory_hostname) }}'
search_regex: OpenSSH
delay: 10
vars:
ansible_connection: local
msg:
description:
- This overrides the normal error message from a failure to meet the required conditions.
type: str
version_added: '2.4'
version_added_collection: ansible.builtin
host:
default: 127.0.0.1
description:
- A resolvable hostname or IP address to wait for.
type: str
path:
description:
- Path to a file on the filesystem that must exist before continuing.
- O(path) and O(port) are mutually exclusive parameters.
type: path
version_added: '1.4'
version_added_collection: ansible.builtin
port:
description:
- Port number to poll.
- O(path) and O(port) are mutually exclusive parameters.
type: int
delay:
default: 0
description:
- Number of seconds to wait before starting to poll.
type: int
sleep:
default: 1
description:
- Number of seconds to sleep between checks.
- Before Ansible 2.3 this was hardcoded to 1 second.
type: int
version_added: '2.3'
version_added_collection: ansible.builtin
state:
choices:
- absent
- drained
- present
- started
- stopped
default: started
description:
- 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.
type: str
timeout:
default: 300
description:
- 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.
type: int
search_regex:
description:
- Can be used to match a string in either a file or a socket connection.
- Defaults to a multiline regex.
type: str
version_added: '1.4'
version_added_collection: ansible.builtin
exclude_hosts:
description:
- List of hosts or IPs to ignore when looking for active TCP connections for V(drained)
state.
elements: str
type: list
version_added: '1.8'
version_added_collection: ansible.builtin
connect_timeout:
default: 5
description:
- Maximum number of seconds to wait for a connection to happen before closing and
retrying.
type: int
active_connection_states:
default:
- ESTABLISHED
- FIN_WAIT1
- FIN_WAIT2
- SYN_RECV
- SYN_SENT
- TIME_WAIT
description:
- The list of TCP connection states which are counted as active connections.
elements: str
type: list
version_added: '2.3'
version_added_collection: ansible.builtin
elapsed:
description: The number of seconds that elapsed while waiting
returned: always
sample: 23
type: int
match_groupdict:
description: 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)
returned: always
sample:
group: match
type: dict
match_groups:
description: Tuple containing all the subgroups of the match as returned by U(https://docs.python.org/3/library/re.html#re.MatchObject.groups)
returned: always
sample:
- match 1
- match 2
type: list