While it is possible to write a playbook in one very large file (and you might start out learning playbooks this way), eventually you’ll want to reuse files and start to organize things. In Ansible, there are three ways to do this: includes, imports, and roles.
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
If you use any
import* Task (
import_tasks, etc.), it will be static.
If you use any
include* Task (
include_role, etc.), it will be dynamic.
include task (which was used for both Task files and Playbook-level includes) is still available, however it is now considered deprecated.
The two modes of operation are pretty simple:
When it comes to Ansible task options like
tags and conditional statements (
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.
import* has some advantages as well as some tradeoffs which users should consider when choosing to use each:
The primary advantage of using
include* statements is looping. When a loop is used with an include, the included tasks or role will be executed once for each item in the loop.
include* does have some limitations when compared to
notifyto trigger a handler name which comes from inside a dynamic include (see note below).
--start-at-taskto begin execution at a task inside a dynamic include.
import* can also have some limitations when compared to dynamic includes:
Regarding the use of
notify for dynamic tasks: it is still possible to trigger the dynamic include itself, which would result in all tasks within the include being run.