W3cubDocs

/Ansible

ansible.windows.win_wait_for – Waits for a condition before continuing

Note

This plugin is part of the ansible.windows collection (version 1.7.3).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install ansible.windows.

To use it in a playbook, specify: ansible.windows.win_wait_for.

Synopsis

  • You can wait for a set amount of time timeout, this is the default if nothing is specified.
  • 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.
  • You can wait for a file to exist or not exist on the filesystem.
  • This module can also be used to wait for a regex match string to be present in a file.
  • You can wait for active connections to be closed before continuing on a local port.

Parameters

Parameter Choices/Defaults Comments
connect_timeout
integer
Default:
5
The maximum number of seconds to wait for a connection to happen before closing and retrying.
delay
integer
The number of seconds to wait before starting to poll.
exclude_hosts
list / elements=string
The list of hosts or IPs to ignore when looking for active TCP connections when state=drained.
host
string
Default:
"127.0.0.1"
A resolvable hostname or IP address to wait for.
If state=drained then it will only check for connections on the IP specified, you can use '0.0.0.0' to use all host IPs.
path
path
The path to a file on the filesystem to check.
If state is present or started then it will wait until the file exists.
If state is absent then it will wait until the file does not exist.
port
integer
The port number to poll on host.
regex
string
Can be used to match a string in a file.
If state is present or started then it will wait until the regex matches.
If state is absent then it will wait until the regex does not match.
Defaults to a multiline regex.

aliases: search_regex, regexp
sleep
integer
Default:
1
Number of seconds to sleep between checks.
state
string
    Choices:
  • absent
  • drained
  • present
  • started ←
  • stopped
When checking a port, started will ensure the port is open, stopped will check that is it closed and 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, absent will check that the file or search string is absent or removed.
timeout
integer
Default:
300
The maximum number of seconds to wait for.

See Also

See also

ansible.builtin.wait_for

The official documentation on the ansible.builtin.wait_for module.

community.windows.win_wait_for_process

The official documentation on the community.windows.win_wait_for_process module.

Examples

- name: Wait 300 seconds for port 8000 to become open on the host, don't start checking for 10 seconds
  ansible.windows.win_wait_for:
    port: 8000
    delay: 10

- name: Wait 150 seconds for port 8000 of any IP to close active connections
  ansible.windows.win_wait_for:
    host: 0.0.0.0
    port: 8000
    state: drained
    timeout: 150

- name: Wait for port 8000 of any IP to close active connection, ignoring certain hosts
  ansible.windows.win_wait_for:
    host: 0.0.0.0
    port: 8000
    state: drained
    exclude_hosts: ['10.2.1.2', '10.2.1.3']

- name: Wait for file C:\temp\log.txt to exist before continuing
  ansible.windows.win_wait_for:
    path: C:\temp\log.txt

- name: Wait until process complete is in the file before continuing
  ansible.windows.win_wait_for:
    path: C:\temp\log.txt
    regex: process complete

- name: Wait until file is removed
  ansible.windows.win_wait_for:
    path: C:\temp\log.txt
    state: absent

- name: Wait until port 1234 is offline but try every 10 seconds
  ansible.windows.win_wait_for:
    port: 1234
    state: absent
    sleep: 10

Return Values

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

Key Returned Description
elapsed
float
always
The elapsed seconds between the start of poll and the end of the module. This includes the delay if the option is set.

Sample:
2.1406487
wait_attempts
integer
always
The number of attempts to poll the file or port before module finishes.

Sample:
1


Authors

  • Jordan Borean (@jborean93)

© 2012–2018 Michael DeHaan
© 2018–2021 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/latest/collections/ansible/windows/win_wait_for_module.html