When we think about Ansible, we often picture its power to automate the configuration management, application deployment, and other DevOps tasks.
However, when automating tasks, we might encounter such instances where we need to reuse specific parts of a single or even multiple playbooks. Hence, instead of copying and pasting the sections between playbooks, splitting the complex playbooks into smaller, more manageable pieces that we can import as required can be essential.
This is where the Ansible import_playbook directive comes into play.
The import_playbook directive allows us to load and execute another playbook within a playbook which lets us structure and modularize the Ansible projects for easier maintenance and readability.
In this tutorial, we will explore the workings of the import_playbook directive to learn how to break and reuse the other playbook sections within our current playbook.
Prerequisites:
To follow along, ensure that you have the following:
- Basic understanding of Ansible and how to write basic playbooks
- Installed Ansible on your local machine or control node
- One or more target machines to run the tasks on
How the Import_Playbook Directive Works
The import_playbook is not technically an Ansible module but a directive. This means that we use it at the top level of a playbook, not inside a task or play.
The following demonstrates the basic syntax of the import_playbook directive:
Let us explore some basic examples on how to work with this directive.
Example 1:
Let us start by defining two playbooks that install a web server and another that installs a database server.
The first playbook is the “webserver.yaml” file as defined in the following:
- hosts: web
tasks:
- name: Install httpd
yum:
name: httpd
state: present
The second playbook is the “database.yaml” file as defined in the following:
- hosts: database
tasks:
- name: Install mariadb
yum:
name: mariadb-server
state: present
Once these playbooks are defined, we can learn how to import and reuse them as necessary.
Example 2: Basic Usage
To use the webserver and database playbooks, we can use the “import_playbook” directive with the path to the playbook that we wish to import as follows:
- import_playbook: web.yml
- import_playbook: database.yml
If we run the “main.yml” playbook, it execues both the “webserver.yaml” and “database.yaml” sequentially.
Conditional Playbook Import
Suppose we have two environments: development and production.
We can use different playbooks for each environment and conditionally import them based on a variable as demonstrated in the following example:
---
- hosts: dev
tasks:
- debug:
msg: "Deploying to Development Environment"
Production.yaml
---
- hosts: prod
tasks:
- debug:
msg: "Deploying to Production Environment"
Finally, to conditionally use them, we can import them as shown in the “main.yaml” file as follows:
- name: Check Environment
hosts: localhost
tasks:
- name: Set environment fact
set_fact:
env: "{{ env_variable }}"
- import_playbook: dev.yml
when: env == "development"
- import_playbook: prod.yml
when: env == "production"
We can now run the playbook that specifies the environment as shown in the following command:
Import Playbook from the Collection
We can also import a playbook from a given collection as shown in the following example:
ansible.builtin.import_playbook: namespace.collection.playbook_name
There you have it!
When to Use the Import_Playbook
Although the import_playbook is very useful, there are some situations in which it’s most applicable. For example:
- Modularization – Break an extensive playbook into smaller logical pieces to improve readability and maintenance.
- Reusability – Use a standard set of tasks or plays across multiple projects without duplicating the code.
- Conditional Execution – Run specific playbooks based on conditions.
NOTE: The import_playbook and include_tasks are different things that carry out different actions. The import_playbook is useful when importing the entire playbooks, while the include_tasks is for task files within a play.
Conclusion
The import_playbook directive is a powerful tool for structuring and organizing the Ansible playbooks. As shown in this tutorial, you can use it to ensure that your automation is modular, maintainable, and efficient.
