Creating Reusable Playbooks
Includes and imports (added in Ansible version 2.4) allow users to break up large playbooks into smaller files, which can be used across multiple parent playbooks or even multiple times within the same Playbook.
Roles allow more than just tasks to be packaged together and can include variables, handlers, or even modules and other plugins. Unlike includes and imports, roles can also be uploaded and shared via Ansible Galaxy.
Ansible has two modes of operation for reusable content: dynamic and static.
In Ansible 2.0, the concept of dynamic includes was introduced. Due to some limitations with making all includes dynamic in this way, the ability to force includes to be static was introduced in Ansible 2.1. Because the include task became overloaded to encompass both static and dynamic syntaxes, and because the default behavior of an include could change based on other options set on the Task, Ansible 2.4 introduces the concept of vs. import
.
If you use any import
Task (importplaybook
, import_tasks
, etc.), it will be _static.If you use any include
Task (includetasks
, include_role
, etc.), it will be _dynamic.
The two modes of operation are pretty simple:
- Ansible pre-processes all static imports during Playbook parsing time.
- Dynamic includes are processed during runtime at the point in which that task is encountered.
When it comes to Ansible task options like tags
and conditional statements (when:
):
- For static imports, the parent task options will be copied to all child tasks contained within the import.
- For dynamic includes, the task options will only apply to the dynamic task as it is evaluated, and will not be copied to child tasks.
Note
Roles are a somewhat special case. Prior to Ansible 2.3, roles were always statically included via the special roles:
option for a given play and were always executed first before any other play tasks (unless pre_tasks
were used). Roles can still be used this way, however, Ansible 2.3 introduced the include_role
option to allow roles to be executed inline with other tasks.
Using include
vs. import
has some advantages as well as some tradeoffs which users should consider when choosing to use each:
Using include
does have some limitations when compared to import
statements:
- Tasks which only exist inside a dynamic include will not show up in
—list-tasks
output. - You cannot use
notify
to trigger a handler name which comes from inside a dynamic include (see note below). - You cannot use
—start-at-task
to begin execution at a task inside a dynamic include.
Using import*
can also have some limitations when compared to dynamic includes:
- As noted above, loops cannot be used with imports at all.
- When using variables for the target file or role name, variables from inventory sources (host/group vars, etc.) cannot be used.
Note
Regarding the use of for dynamic tasks: it is still possible to trigger the dynamic include itself, which would result in all tasks within the include being run.
See also
- Review the basic Playbook language features
- Using Variables
- All about variables in playbooks
- Conditionals in playbooks
- Loops in playbooks
- Best Practices
- Various tips about managing playbooks in the real world
- How to share roles on galaxy, role management
- GitHub Ansible examples
- Complete playbook files from the GitHub project source
- Questions? Help? Ideas? Stop by the list on Google Groups