Including and Importing¶
Topics
Includes vs. Imports¶
As noted in Creating Reusable Playbooks, include and import statements are very similar, however the Ansible executor engine treats them very differently.
All
import*
statements are pre-processed at the time playbooks are parsed.All
include*
statements are processed as they are encountered during the execution of the playbook.
Please refer to Creating Reusable Playbooks for documentation concerning the trade-offs one may encounter when using each type.
Also be aware that this behaviour changed in 2.4. Prior to Ansible 2.4, only include
was available and it behaved differently depending on context.
New in version 2.4.
Importing Playbooks¶
It is possible to include playbooks inside a master playbook. For example:
- import_playbook: webservers.yml
- import_playbook: databases.yml
The plays and tasks in each playbook listed will be run in the order they are listed, just as if they had been defined here directly.
Prior to 2.4 only include
was available and worked for both playbooks and tasks as both import and include.
New in version 2.4.
Including and Importing Task Files¶
Breaking tasks up into different files is an excellent way to organize complex sets of tasks or reuse them. A task file simply contains a flat list of tasks:
# common_tasks.yml
- name: placeholder foo
command: /bin/foo
- name: placeholder bar
command: /bin/bar
You can then use import_tasks
or include_tasks
to execute the tasks in a file in the main task list:
tasks:
- import_tasks: common_tasks.yml
# or
- include_tasks: common_tasks.yml
You can also pass variables into imports and includes:
tasks:
- import_tasks: wordpress.yml
vars:
wp_user: timmy
- import_tasks: wordpress.yml
vars:
wp_user: alice
- import_tasks: wordpress.yml
vars:
wp_user: bob
See Variable precedence: Where should I put a variable? for more details on variable inheritance and precedence.
Task include and import statements can be used at arbitrary depth.
Note
Static and dynamic can be mixed, however this is not recommended as it may lead to difficult-to-diagnose bugs in your playbooks.
The
key=value
syntax for passing variables to import and include is deprecated. Use YAMLvars:
instead.
Includes and imports can also be used in the handlers:
section. For instance, if you want to define how to restart Apache, you only have to do that once for all of your playbooks. You might make a handlers.yml
that looks like:
# more_handlers.yml
- name: restart apache
service:
name: apache
state: restarted
And in your main playbook file:
handlers:
- include_tasks: more_handlers.yml
# or
- import_tasks: more_handlers.yml
Note
Be sure to refer to the limitations/trade-offs for handlers noted in Creating Reusable Playbooks.
You can mix in includes along with your regular non-included tasks and handlers.
Including and Importing Roles¶
Please refer to Roles for details on including and importing roles.
See also
- YAML Syntax
Learn about YAML syntax
- Working With Playbooks
Review the basic Playbook language features
- Best Practices
Various tips about managing playbooks in the real world
- Using Variables
All about variables in playbooks
- Conditionals
Conditionals in playbooks
- Loops
Loops in playbooks
- All modules
Learn about available modules
- Should you develop a module?
Learn how to extend Ansible by writing your own modules
- GitHub Ansible examples
Complete playbook files from the GitHub project source
- Mailing List
Questions? Help? Ideas? Stop by the list on Google Groups