ansible/docs/docsite/rst/playbooks_reuse_includes.rst

Including and Importing

Topics

Includes vs. Imports

As noted in playbooks_reuse, 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 encountered during the execution of the playbook.

Please refer to playbooks_reuse 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 that Ansible version only include was available, and it behaved differently depending on context.

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.

2.4

Including and Importing Task Files

Use of included task lists is a great way to define a role that system is going to fulfill. A task include 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 include this file in your 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 wp_user=timmy
- import_tasks: wordpress.yml wp_user=alice
- import_tasks: wordpress.yml wp_user=bob

Variables can also be passed to include files using an alternative syntax, which also supports structured variables like dictionaries and lists:

tasks:
- include_tasks: wordpress.yml
  vars:
    wp_user: timmy
    ssh_keys:
    - "{{ lookup('file', 'keys/one.pub') }}"
    - "{{ lookup('file', 'keys/two.pub') }}"

Using either syntax, variables passed in can then be used in the included files. These variables will only be available to tasks within the included file. See ansible_variable_precedence for more details on variable inheritance and precedence.

Task include 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.

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 playbooks_reuse.

You can mix in includes along with your regular non-included tasks and handlers.

Including and Importing Roles

Please refer to playbooks_reuse_roles for details on including and importing roles.

YAMLSyntax

Learn about YAML syntax

playbooks

Review the basic Playbook language features

playbooks_best_practices

Various tips about managing playbooks in the real world

playbooks_variables

All about variables in playbooks

playbooks_conditionals

Conditionals in playbooks

playbooks_loops

Loops in playbooks

modules

Learn about available modules

dev_guide/developing_modules

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