Updated March 31, 2023
Introduction to Ansible When
Ansible “When” statement is a conditional statement that runs the particular task if the condition is met and the condition should be based on the registered variable output, loop, gathered facts, declared variable output, and to create the dependencies between the tasks that is when the output from the first task matches certain value then the second task should be executed.
Syntax:
Ansible “When” condition is declared with the when: keyword.
How does When Condition Work in Ansible?
In the Ansible YAML language, the When is considered as the conditional statement like the IF statement in the other programming languages, it checks if the specified condition is satisfied, then it executes the block likewise in the YAML language, the when statement runs the particular task when the condition is met.
You can attach the when statement to tasks that you need to check the condition.
You can run the task for conditions:
- Based on the value set in the variable.
- Based on the register_variable output.
- Based on the gathered facts.
- Based on the output from the previous tasks.
- Based on the command output.
- Based on the loop and so on.
Example:
Code:
---
- name: Ansible simple playbook for condition
hosts: linuxservers
vars:
test: 1
tasks:
- name: when condition example
ansible.builtin.debug:
msg: When condition task is executed
when: "{{ test }} == 1"
Output:
In the above example, we have first declared the variable named test, and in the task, we are checking the value of the variable. If it is 1, then only the particular task is executed. You can provide when conditions to any number of tasks in the playbook.
Examples of Ansible When
Given below are the examples of Ansible When:
Example #1
Running the tasks based on the facts gathered.
In this example, we will run the task(s) only certain conditions are matched from the retrieved values from the gathered facts variable.
Code:
---
- name: Ansible playbook conditions with gathered facts
hosts: windowsservers
tasks:
- name: Stop the Spooler service if the Server is windows server.
win_service:
name: spooler
start_mode: manual
state: stopped
when: ansible_facts['os_family'] == "Windows"
Output:
In the above example, the ansible_facts variable gathers the facts on the remote servers. We can use the os_family property, which stores the version of the operating system that can be used and matches the OS family, then it stops the spooler service.
If you put the wrong OS name or the windows instead of Windows, then it will skip the task because ansible is a case-sensitive language. We are changing the os name from Windows to Win, and it will skip the task.
Code:
when: ansible_facts['os_family'] == "Win"
Output:
To check all the facts are gathered, you can use the separate playbook below or add in the same playbook with a different task.
Code:
---
- name: Ansible Playbook to gather tasks on remote servers
hosts: windowsservers
tasks:
- name: Gather facts
ansible.builtin.debug:
var: ansible_facts
To use the multiple conditions, group them with the parentheses.
Code:
---
- name: Ansible playbook to reboot pending vms based on conditions
hosts: windowsservers
tasks:
- name: reboot the pending windows servers
win_reboot:
when: (ansible_facts['os_family'] == "Windows") and
(ansible_facts['reboot_pending'] == "yes")
Or you can write the above condition like:
when:
- ansible_facts['os_family'] == "Windows"
- ansible_facts['reboot_pending'] == "yes"
Output:
You can use multiple operators and conditions for the task.
Example #2
Using the register variable value to the different tasks.
We can use the register variable, which is used to store the output from the task into the variable. Then, we can leverage this variable output into the other tasks with the “when” condition to filter the output, and if it matches, then to only execute the particular task.
In the below example, the first task will get the content of the servers.txt into the variable called dirout, and we need to filter the variable output using the when condition, and if it matches the declared variable findstr value, then it executes tasks and displays the message.
Code:
---
- name: Register variable test playbook
hosts: windowsservers
vars:
findstr: "AD"
tasks:
- name: store the windows directory output
win_shell: get-content c:\temp\servers.txt
register: dirout
- name: check if the directory exist
ansible.builtin.debug:
msg: "{{ findstr }} keyword exist"
when: dirout.stdout.find("{{ findstr }}") == 0
Output:
If the condition doesn’t match, it skips the current task execution.
Example #3
Checking if the directory is empty using the Ansible When condition.
The below playbook will check if the directory is empty using the register variable output and the when condition. Although we can check the empty directory using the command, we will use the register variable method here.
Code:
---
- name: Ansible playbook to check if the directory is empty.
hosts: windowsservers
vars:
dirpath: c:\mydir
tasks:
- name: Check empty directory
win_shell: dir {{ dirpath }}
register: checkdir
- name: Display if the Dirctory is empty
ansible.builtin.debug:
msg: "{{ dirpath }} folder is empty"
when: checkdir.stdout == ""
Output:
If the folder is not empty, then it will skip the task.
Example #4
Check if the folder exists with the multiple when conditions.
This example will check if the mentioned directory exists on the windows server using the registered variable output. If the variable has value, then it is considered as succeeded, and if the task fails, then the variable doesn’t hold the value, so we will use “is failed” in the when condition.
Code:
---
- name: Ansible playbook to check if the folder is exist
hosts: windowsservers
vars:
dirpath: c:\mydir111
tasks:
- name: Check empty directory
win_shell: dir {{ dirpath}}
register: checkdir
ignore_errors: true
- name: Display output if the folder is exist
ansible.builtin.debug:
msg: "{{ dirpath }} folder is exist"
when: checkdir is succeeded
- name: Display output if the folder not exist
ansible.builtin.debug:
msg: "{{ dirpath }} folder does not exist"
when: checkdir is failed
Output:
Conclusion
Ansible When conditions are pretty much useful like the IF condition in the programming languages. It avoids creating multiple tasks or is helpful in restricting creating multiple groups in the inventory file.
Recommended Articles
This is a guide to Ansible When. Here we discuss the introduction, how does when condition work in ansible? And examples, respectively. You may also have a look at the following articles to learn more –
