Updated April 6, 2023
Definition of Ansible Include
Ansible Include module which is a part of the ansible-base and the default module available with the ansible installation used to include a file with a list of plays or tasks to be executed in the current playbook and it can be a single include file the multiple include files, meaning it calls the other playbooks tasks or plays and this module also works for the windows targets.
Syntax:
This module uses the syntax “Include”.
Parameters:
free-form: optional
This module allows you to specify the name of the file directly without any other options.
How does the Include module work in Ansible?
In the different programming languages, to simplify the program we divide the programs into multiple files and modules, and to use them in the script we use the different commands to import them so we don’t need to write the program again.
The Include module in the Ansible works a similar way. We create a playbook to run multiple tasks together resulting in long playbooks sometimes which can be confusing to understand and modify. Instead, we write the different playbooks combining one or multiple tasks and then add them to the main playbook.
For example, Let say, we need to write the playbook which downloads the zip file from the internet, copies it to the target servers, and unzip the file at the destination folder. Consider this all tasks are written under the main.yml file. Our main.yml file will look like this.
Main.yml
– Task1: Download the zip file from the internet.
– Task2: Copy the zip file on the target server.
– Task3: Extract the zip file at the target location.
Once we divide the above tasks into the playbooks for example, Downloadfile.yml, copyfile.yml, and extracfile.yml respectively then we can add them into the main.yml playbook as shown below.
Main.yml
include: Downloadfile.yml
include: copyfile.yml
include: extractfile.yml
We can now use the above XML files in multiple playbooks if we have the same requirement. You can combine many options like you can add task1 and task2 together in the single playbook and task3 in the other playbook or task1 and task2 in the different playbooks and task3 in the main playbook as per your requirement.
So Ansible include module has several benefits.
- Helps to make the overall playbook small and organized.
- Helps to get rid of the repetitive tasks by using the earlier created playbooks.
- Helps when the target servers have a dependency, for example, we need to put the server into maintenance and take the servers out of maintenance which are in separate playbooks in the main playbook then you can add both the files with include module at the start and the end of the main playbook respectively.
Disadvantage
It runs the entire playbook so if multiple playbooks have the same set of servers then it consumes the time and also gathers the facts multiple times if the gather_facts is not disabled.
The below example shows how we can use the include function to add another playbook in the main playbook.
Includepb.yml
---
- name: Ansible playbook to test Include module
include: servicepb.yml
Servicepb.yml
---
- name: Ansible playbook to stop the spooler service
hosts: winservers
tasks:
- name: Stop the spooler service
win_service:
name: spooler
start_mode: manual
state: stopped
When we run includepb.yml playbook,
ansible-playbook includepb.yml
You will get the deprecated module warning because whatever the Ansible version you are running currently, include module will be removed in version 2.12 and an alternate way to use this command is import_playbook.
---
- name: Ansible playbook to test Include module
Import_playbook: servicepb.yml
Examples
Let us discuss examples of Ansible Include.
Example #1: Ansible “Include” example for adding multiple playbooks.
Suppose you have the below main playbook called includepb.yml
---
- name: Ansible playbook for the include module
hosts: winsservers
tasks:
- name: Task to stop the spooler service
win_service:
name: spooler
start_mode: manual
state: stopped
- name: Copy ansible.cfg file to the c:\temp
win_copy:
src: /etc/ansible/ansible.cfg
dest: c:\temp\
Now we divide both the tasks into two files called servicepb.yml and copypb.yml respectively. To include both the playbooks in the includepb.yml file,
---
- name: Calling service playbook
include: servicepb.yml
- name: calling copy playbook
include: copypb.yml
Output:
ansible-playbook includepb.yml
If you have noticed, each playbook runs individually and gathers the facts. So if you are using the include module for the same set of servers then it is not that useful. The other alternate option is to import the tasks rather than the playbooks using include_tasks.
If you want to run the individual tasks then your playbooks should contain only the tasks.
servicepb.yml
---
- name: Task to stop the spooler service
win_service:
name: spooler
start_mode: manual
state: started
copyob.yml
---
- name: Copying ansible.cfg file
win_copy:
src: /etc/ansible/ansible.cfg
dest: c:\temp\
includepb.yml
---
- name: Ansible playbook for Include_tasks
hosts: winservers
tasks:
- include_tasks: servicepb.yml
- include_tasks: copypb.yml
ansible-playbook includepb.yml
Output:
You can notice that the different tasks are imported and ran against the specified hosts in the main playbook (includepb.yml).
Example #2: Adding another playbook with the different tasks.
In this example, we will import the ansible-playbook into the current playbook along with the other tasks.
Servicepb.yml
---
- name: Ansible playbook to stop the spooler service
hosts: winservers
tasks:
- name: Stop the spooler service
win_service:
name: spooler
start_mode: manual
state: stopped
inludepb.yml
---
- name: Ansible playbook for importing playbook
hosts: winservers
tasks:
- debug:
msg: "Task1 to display"
- name: Task to copy ansible.cfg to windows servers
win_copy:
src: /etc/ansible/ansible.cfg
dest: c:\temp\
- name: import servicepb.yml
include: servicepb.yml
ansible-playbook includepb.yml
Output:
You can also add the include task at the top and you can also specify the condition to run the include task with when.
Conclusion
Ansible “include” module is useful when we need to run multiple tasks on the different environment or the different set of servers but if you have the same set of servers then the include module is not that useful because it runs the different tasks on the same servers, instead, we can use the include_tasks to just import the tasks.
Recommended Articles
This is a guide to Ansible Include. Here we discuss the Definition, syntax, How does the include module work in Ansible? examples with code implementation. You may also have a look at the following articles to learn more –
