Updated April 12, 2023
Introduction to Ansible wait_for
In Ansible, we face many situations where a task is dependent on a service, port or system’s state. But that state is expected to occur after some time due to a connection reset, server reboot, execution time taken by a code or time taken to start a service. So we need to wait for it to happen. Now Ansible is so rich in its module treasure that it has a module named wait_for which enables our playbook to wait for a state or task completion on remote target machines. Using this module we will wait for a condition to occur before continuing with next tasks our playbook.
What is Ansible wait_for?
Ansible wait_for module can actually be used with or without a condition on remote target hosts and it checks for that condition’s state after a specified time in seconds.
When using module, one must remember below points:
- If you just need to wait and not checking any condition, then use only timeout parameter with time in seconds to wait. This completely work on your assumption of required waiting time.
- This module can be used for conditions like for starting a guest to with virt module, File to exits, match a regex in file.
- For Microsoft Windows remote target machines, use module named win_wait_for.
- This module is having backward compatibility support going ahead in next version, by Ansible core team.
How does Ansible wait_for work?
To work with Ansible wait_for module, we must know about the acceptable parameters and their acceptable options. Some of the parameters have default values set, so this must also be noted.
Given below is a list of parameters:
1. timeout: Default is 300 seconds. Maximum number of seconds to wait for. This shouldn’t be used with other conditions, because then it will fail.
2. state: Below are the acceptable states:
- started: whether port is open.
- stopped: whether port is closed.
- drained: Whether connection is active.
- present: Whether a string is present in a file or string.
- absent: whether file is removed or absent.
3. sleep: Default is 1 second. This is to sleep between checks.
4. search_regex: To check a string in file or socket connection.
5. port: Port number to check.
6. path: Path of a file which must be existing before continuing.
7. msg: This is the message which will be printing instead of normal error message in case of failures.
8. host: The IP or hostname to wait for.
9. exclude_hosts: The list of hosts, not to check when looking for active connections (TCP).
10. delay: Default is 0. This represents the number of seconds to wait for next polling.
11. connect_timeout: Default is 5 seconds. This is to specify the time to wait for a connection to establish before closing and try again.
12. active_connection_states: This is the list of connections (TCP) which can be counted as active session. Default values are “TIME_WAIT”, “FIN_WAIT2, “FIN_WAIT1”, “ESTABLISHED”, “SYN_SENT”, “SYN_RECV”.
The unique return values by this module, this will enable us to know the actual execution happened on remote target systems.
Given below are such unique return values:
1. elapsed: The seconds elapsed while waiting.
2. match_groupdict: This is the dictionary containing all the subgroups name matched by key given.
3. match_groups: Tuple containing all the subgroup of the match.
Examples of Ansible wait_for
Given below are the examples mentioned:
Here we have one Ansible controller node named as ansible-controller. As target nodes, we have two remote machines. First machine is a Red Hat Enterprise Linux machine named as host-one and second machine is an Ubuntu machine named as host-two. We will run our playbooks on Ansible controller machine and make changes on remote target machines.
Example #1
In this example, we have a playbook like below, using which we will try to reboot the remote machines and the use wait_for module to wait for 30 seconds and then we check the uptime on same machines.
Code:
---
-hosts:
all
tasks:
-name: Here we are rebooting the remote machines using Ansible reboot module reboot:
-name: Here we will wait for 30 seconds and then continue with next wait_for:
timeout: 30
-name: Here we are checking the uptime on shell: uptime
register: var_uptime
-name: Here we are printing the output of debug:
var: var_uptime.stdout_lines
Now running this playbook like below, we have below output where we can see that servers were rebooted and then we waited for 30 seconds and then uptime was displayed.
ansible-playbook ansible_wait_for_reboot.yaml -v
Output:
Example #2
In this example, we have a playbook like below where we are checking for a httpd.conf file, if this file exists then make modification in this file. If this file doesn’t exists then wait for it. For this we have a playbook like below.
Code:
---
-hosts: host-one tasks:
-name: Here we check for file httpd.conf
existance wait_for:
path: /etc/httpd/conf/httpd.conf
state: present
name: Here we are placing line in this file using lineinfile
module lineinfile:
path: /etc/httpd/conf/httpd.conf regexp: '^Listen '
insertafter: '^#Listen ' line: Listen 8443
Here, initially we did not have httpd package installed on host-one, so playbook was waiting for the httpd.conf file, as this file is provided by httpd package. Then, while it was waiting for httpd to be installed and file to be created, we went to host-one and installed httpd package in background. Now in output, you can see the elapsed time is 77 seconds which shows it waited for 77 seconds.
ansible-playbook ansible_wait_for_file.yaml -v
Output:
Conclusion
As we saw in this article, this module is really helpful in practical or real time scenarios, where you really have to wait for some time so that a condition can complete on remote target systems. Operations like patching, provisioning leverages it very well. But as you know we shall be very aware about its available options before using it. So learn it first and then use it.
Recommended Articles
This is a guide to Ansible wait_for. Here we discuss what is ansible wait_for? how does ansible wait_for work with respective examples. You may also have a look at the following articles to learn more –
