Working with include and import module in Ansible

In this section we will use include and import module to add another tasks or complete playbook into another playbook.

include module

Use include module to add tasks to the playbook

We can create separate yml file which will only contain tasks using the YAML syntax which can be used inside a playbook by using include module. I have created this tasks-1.yml file with following content:

[ansible@controller ~]$ cat tasks-1.yml
---
 - name: Play 1 - Task 2
   debug:
     msg: Play 1 - Task 2

...

In this example I have used --- to mark the start of the playbook and ... to mark the end of the playbook as this yml file is going to be included in another playbook so it is recommended to mark the start and end of the playbook

Now I have the parent playbook include_tasks.yml which will contain our tasks-1.yml

[ansible@controller ~]$ cat include_tasks.yml
---
 - name: Working with include_tasks module
   hosts: localhost
   gather_facts: false
   tasks:
     - name: Play 1 - Task 1
       debug:
         msg: "Play 1 - Task 1"
     - include: tasks-1.yml

Now let us execute this playbook:

[ansible@controller ~]$ ansible-playbook include_tasks.yml

PLAY [Working with include_tasks module] *****************************************************************************

TASK [Play 1 - Task 1] ***********************************************************************************************
ok: [localhost] => {
    "msg": "Play 1 - Task 1"
}

TASK [Play 1 - Task 2] ***********************************************************************************************
ok: [localhost] => {
    "msg": "Play 1 - Task 2"
}

PLAY RECAP ***********************************************************************************************************
localhost                  : ok=2    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

So both the tasks i.e. the one which was included from tasks-1.yml and the other which was part of the playbook are successfully executed. If you notice the output is not showing any indication whatsoever that any include was used or all the tasks were part of the playbook.

Use include module to add one complete playbook into another

Playbook files can include other whole playbook files. This construct can be useful to tie together a few independent playbooks into a larger, more comprehensive playbook. Playbook inclusion is a bit more primitive than task inclusion. You cannot perform variable substitution when including a playbook, you cannot apply conditionals, and you cannot apply tags, either. The playbook files to be included must exist at the time of execution as well.

Here I have created a new playbook include_playbook.yml which uses include module to import another playbook i.e. play2.yml and it also uses include to add another

NOTE:

Observe the syntax, We have defined empty - (hyphen) which denotes that the playbook contains a list item wherein the current playbook is one of the list item while we have added another list item at the end of playbook using another hyphen.

---
# The minus in YAML indicates a list item. The playbook contains
# a list of plays, with each play being a dictionary
-
   name: include playbook
   hosts: localhost
   gather_facts: false
   tasks:
     - name: Play 1 - Task 1
       debug:
         msg: "Play 1 - Task 1"
     - include: tasks-1.yml

- include: play2.yml
...

HINT:

Prior to Ansible 2.4, playbook inclusion was achieved using the include keyword—however, this is deprecated and will be removed in Ansible 2.8, and so it should not be used

Here is the content of play2.yml

[ansible@controller ~]$ cat play2.yml
---
 - name: Play 2
   hosts: localhost
   gather_facts: false
   tasks:
     - name: Play 2 - Task 1
       debug:
         msg: "Play 2 - Task 1"
...

Now we will execute include_playbook.yml playbook:

[ansible@controller ~]$ ansible-playbook include_playbook.yml
[DEPRECATION WARNING]: 'include' for playbook includes. You should use 'import_playbook' instead. This feature will
be removed in version 2.12. Deprecation warnings can be disabled by setting deprecation_warnings=False in
ansible.cfg.

PLAY [include playbook] **********************************************************************************************

TASK [Play 1 - Task 1] ***********************************************************************************************
ok: [localhost] => {
    "msg": "Play 1 - Task 1"
}

TASK [Play 1 - Task 2] ***********************************************************************************************
ok: [localhost] => {
    "msg": "Play 1 - Task 2"
}

PLAY [Play 2] ********************************************************************************************************

TASK [Play 2 - Task 1] ***********************************************************************************************
ok: [localhost] => {
    "msg": "Play 2 - Task 1"
}

PLAY RECAP ***********************************************************************************************************
localhost                  : ok=3    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

We are getting a DEPRECATED warning because include playbook is not recommended anymore and we should use import_playbook module instead. But the playbook has executed successfully and tasks from both the PLAY have been executed.

include_tasks module

Next we will analyse the include_tasks module using the same set of playbook and tasks-1.yml file. But we will replace include with include_tasks module inside include_tasks.yml playbook

---
 - name: Working with include_tasks module
   hosts: localhost
   gather_facts: false
   tasks:
     - name: Play 1 - Task 1
       debug:
         msg: "Play 1 - Task 1"
     - include_tasks: tasks-1.yml

Now let us execute this playbook:

[ansible@controller ~]$ ansible-playbook include_tasks.yml

PLAY [Working with include_tasks module] *****************************************************************************

TASK [Play 1 - Task 1] ***********************************************************************************************
ok: [localhost] => {
    "msg": "Play 1 - Task 1"
}

TASK [include_tasks] *************************************************************************************************
included: /home/ansible/tasks-1.yml for localhost

TASK [Play 1 - Task 2] ***********************************************************************************************
ok: [localhost] => {
    "msg": "Play 1 - Task 2"
}

PLAY RECAP ***********************************************************************************************************
localhost                  : ok=3    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

As you can see from the output, the include tasks was counted as another TASK and in total 3 tasks were executed including the one which was included. The TASK 2 informs the operator of the include_tasks activity which was performed by the playbook unlike include module.

import_tasks and import_playbook module

Now in this section we will use import_tasks and import_playbook module in the same play. Earlier we had got a DEPRECATED WARNING when we used include for adding a playbook so we will use the same example but with import_tasks and import_playbook this time:

---
# The minus in YAML indicates a list item. The playbook contains
# a list of plays, with each play being a dictionary
-
   name: import playbook
   hosts: localhost
   gather_facts: false
   tasks:
     - name: Play 1 - Task 1
       debug:
         msg: "Play 1 - Task 1"
     - import_tasks: tasks-1.yml

- import_playbook: play2.yml
...

You can check our import_playbook.yml file, here I am using the same list format by adding a hyphen and then towards the end I have added import_playbook to import play2.yml inside the same play. We are also using import_tasks to import the content of tasks-1.yml in the PLAY-1

What's Next

Now next in our Ansible Tutorial we will learn all about Ansible roles and it's directory structure