Documentation

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.
  • 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 1.6 and later, this module can also be used to wait for a file to be available or absent on the filesystem.
  • In 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.

Options

parameter required default choices comments
active_connection_states
(added in 2.3)
no [u'ESTABLISHED', u'SYN_SENT', u'SYN_RECV', u'FIN_WAIT1', u'FIN_WAIT2', u'TIME_WAIT']
    The list of tcp connection states which are counted as active connections
    connect_timeout
    no 5
      maximum number of seconds to wait for a connection to happen before closing and retrying
      delay
      no
        number of seconds to wait before starting to poll
        exclude_hosts
        (added in 1.8)
        no
          list of hosts or IPs to ignore when looking for active TCP connections for drained state
          host
          no 127.0.0.1
            A resolvable hostname or IP address to wait for
            path
            (added in 1.4)
            no
              path to a file on the filesytem that must exist before continuing
              port
              no
                port number to poll
                search_regex
                (added in 1.4)
                no
                  Can be used to match a string in either a file or a socket connection. Defaults to a multiline regex.
                  sleep
                  (added in 2.3)
                  no 1
                    Number of seconds to sleep between checks, before 2.3 this was hardcoded to 1 second.
                    state
                    no started
                    • present
                    • started
                    • stopped
                    • absent
                    • drained
                    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
                    no 300
                      maximum number of seconds to wait for

                      Examples

                      # wait 300 seconds for port 8000 to become open on the host, don't start checking for 10 seconds
                      - wait_for:
                          port: 8000
                          delay: 10
                      
                      # wait 300 seconds 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
                      
                      # wait 300 seconds 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
                      
                      # wait until the file /tmp/foo is present before continuing
                      - wait_for:
                          path: /tmp/foo
                      
                      # wait until the string "completed" is in the file /tmp/foo before continuing
                      - wait_for:
                          path: /tmp/foo
                          search_regex: completed
                      
                      # wait until the lock file is removed
                      - wait_for:
                          path: /var/lock/file.lock
                          state: absent
                      
                      # wait until the process is finished and pid was destroyed
                      - wait_for:
                          path: /proc/3466/status
                          state: absent
                      
                      # wait 300 seconds for port 22 to become open and contain "OpenSSH", don't assume the inventory_hostname is resolvable
                      # and don't start checking for 10 seconds
                      - local_action: wait_for port=22 host="{{ ansible_ssh_host | default(inventory_hostname) }}" search_regex=OpenSSH delay=10
                      

                      Notes

                      Note

                      • The ability to use search_regex with a port connection was added in 1.7.

                      Status

                      This module is flagged as stableinterface which means that the maintainers for this module guarantee that no backward incompatible interface changes will be made.

                      Support

                      This module is maintained by those with core commit privileges

                      For more information on what this means please read Module Support

                      For help in developing on modules, should you be so inclined, please read Community Information & Contributing, Helping Testing PRs and Developing Modules.