mirror of https://github.com/ansible/ansible.git
Imports and includes (#25399)
Initial commit to split includes into static imports/dynamic includes
This implements the new include/import syntax for Ansible 2.4:
* include_{tasks,role,variables} = dynamic
* import_{playbook,tasks,role} = static
The old bare `include` will be considered deprecated, as will any use of the `static: {yes|no}` option.
This also adds docs for import/include and reorganizing the "Playbook Reuse" section of the documentation.
pull/25852/head
James Cammarata
8 years ago
committed by
GitHub
parent
3549391673
commit
483df9c5f8
@ -0,0 +1,143 @@
|
||||
Directives Glossary
|
||||
===================
|
||||
|
||||
This section lists the common playbook objects and their directives.
|
||||
Note that not all directives affect the object itself and might just be there to be inherited by other contained objects.
|
||||
Aliases for the directives are not reflected here, nor are mutable ones; for example, `action` in task can be substituted by the name of any module plugin.
|
||||
|
||||
Be aware that this reflects the 'current development branch' and that the keywords do not have 'version_added' information.
|
||||
|
||||
.. contents::
|
||||
:local:
|
||||
:depth: 1
|
||||
|
||||
|
||||
Play
|
||||
----
|
||||
- **accelerate:** DEPRECATED. Set to True to use the accelerate connection plugin.
|
||||
- **accelerate_ipv6:** DEPRECATED. Set to True to force the accelerate plugin to use ipv6 for it's connection.
|
||||
- **accelerate_port:** DEPRECATED. Set to override default port use for accelerate connection.
|
||||
- **always_run:** DEPRECATED. Forces a task to run even in check mode. Use check_mode directive instead.
|
||||
- **any_errors_fatal:** Force any un-handled task errors on any host to propagate to all hosts and end the play.
|
||||
- **become:** Boolean that controls if privilege escalation is used or not on Task execution.
|
||||
- **become_flags:** A string of flag(s) to pass to the privilege escalation program when ``become`` is True.
|
||||
- **become_method:** Which method of privilege escalation to use; for example sudo/su/etc.
|
||||
- **become_user:** User that you 'become' after using privilege escalation. The remote/login user must have permissions to become this user.
|
||||
- **check_mode:** A boolean that controls if a task is executed in 'check' mode.
|
||||
- **connection:** Allows you to change the connection plugin used for tasks to execute on the target.
|
||||
- **environment:** A dictionary that gets converted into environment vars to be provided for the task upon execution.
|
||||
- **fact_path:** Set the fact path option for the fact gathering plugin controlled by ``gather_facts``.
|
||||
- **force_handlers:** Force notified handler execution for hosts even if they failed during the play; it will not trigger if the play itself fails.
|
||||
- **gather_facts:** A boolean that controls if the play will automatically run the 'setup' task to gather facts for the hosts.
|
||||
- **gather_subset:** Allows you to pass subset options to the fact gathering plugin controlled by ``gather_facts``.
|
||||
- **gather_timeout:** Allows you to set the timeout for the fact gathering plugin controlled by ``gather_facts``.
|
||||
- **handlers:** A section with tasks that are treated as handlers, these won't get executed normally, only when notified. After each section of tasks is complete.
|
||||
- **hosts:** A list of groups, hosts or host pattern that translates into a list of hosts that are the play's target.
|
||||
- **ignore_errors:** Boolean that allows you to ignore task failures and continue with the play. It does not affect connection errors.
|
||||
- **max_fail_percentage:** Used to abort the run after a given percentage of hosts in the current batch has failed.
|
||||
- **name:** Identifier. Used mostly for documentation. In the case of tasks/handlers it can be an identifier.
|
||||
- **no_log:** Boolean that controls information disclosure.
|
||||
- **order:** UNDOCUMENTED!!
|
||||
- **port:** Used to override the default port used in a connection.
|
||||
- **post_tasks:** A list of tasks to execute after the ``tasks`` section.
|
||||
- **pre_tasks:** A list of tasks to execute before ``roles``.
|
||||
- **remote_user:** User used to log into the target via the connection plugin. AKA login user.
|
||||
- **roles:** UNDOCUMENTED!!
|
||||
- **run_once:** Boolean that will bypass the host loop, forcing the task to execute on the first host available and will also apply any facts to all active hosts.
|
||||
- **serial:** Defines the 'batch' of hosts to execute the current play until the end.
|
||||
- **strategy:** Allows you to choose the connection plugin to use for the play.
|
||||
- **tags:** Tags applied to the task or included tasks, this allows selecting subsets of tasks from the command line.
|
||||
- **tasks:** Main list of tasks to execute in the play, they run after ``roles`` and before ``post_tasks``.
|
||||
- **vars:** Dictionary/map of variables
|
||||
- **vars_files:** List of files that contain vars to include in the play.
|
||||
- **vars_prompt:** List of variables to prompt for.
|
||||
- **vault_password:** Secret used to decrypt vaulted files or variables.
|
||||
|
||||
|
||||
Role
|
||||
----
|
||||
- **always_run:** DEPRECATED. Forces a task to run even in check mode. Use check_mode directive instead.
|
||||
- **any_errors_fatal:** Force any un-handled task errors on any host to propagate to all hosts and end the play.
|
||||
- **become:** Boolean that controls if privilege escalation is used or not on Task execution.
|
||||
- **become_flags:** A string of flag(s) to pass to the privilege escalation program when ``become`` is True.
|
||||
- **become_method:** Which method of privilege escalation to use; for example sudo/su/etc.
|
||||
- **become_user:** User that you 'become' after using privilege escalation. The remote/login user must have permissions to become this user.
|
||||
- **check_mode:** A boolean that controls if a task is executed in 'check' mode
|
||||
- **connection:** Allows you to change the connection plugin used for tasks to execute on the target.
|
||||
- **delegate_facts:** Boolean that allows you to apply facts to delegated host instead of inventory_hostname.
|
||||
- **delegate_to:** Host to execute task instead of the target (inventory_hostname). Connection vars from the delegated host will also be used for the task.
|
||||
- **environment:** A dictionary that gets converted into environment vars to be provided for the task upon execution.
|
||||
- **ignore_errors:** Boolean that allows you to ignore task failures and continue with play. It does not affect connection errors.
|
||||
- **no_log:** Boolean that controls information disclosure.
|
||||
- **port:** Used to override the default port used in a connection.
|
||||
- **remote_user:** User used to log into the target via the connection plugin. Also known as login user.
|
||||
- **run_once:** Boolean that will bypass the host loop, forcing the task to execute on the first host available and will also apply any facts to all active hosts.
|
||||
- **tags:** Tags applied to the task or included tasks, this allows selecting subsets of tasks from the command line.
|
||||
- **vars:** Dictionary/map of variables
|
||||
- **when:** Conditional expression; determines if an iteration of a task is run or not.
|
||||
|
||||
|
||||
Block
|
||||
-----
|
||||
- **always:** List of tasks, in a block, that execute no matter if there is an error in the block or not.
|
||||
- **always_run:** DEPRECATED, forces a task to run even in check mode, use check_mode directive instead.
|
||||
- **any_errors_fatal:** Force any un-handled task errors on any host to propagate to all hosts and end the play.
|
||||
- **become:** Boolean that controls if privilege escalation is used or not on Task execution.
|
||||
- **become_flags:** A string of flag(s) to pass to the privilege escalation program when ``become`` is True.
|
||||
- **become_method:** Which method of privilege escalation to use. i.e. sudo/su/etc.
|
||||
- **become_user:** User that you 'become' after using privilege escalation, the remote/login user must have permissions to become this user.
|
||||
- **block:** List of tasks in a block.
|
||||
- **check_mode:** A boolean that controls if a task is executed in 'check' mode
|
||||
- **connection:** Allows you to change the connection plugin used for tasks to execute on the target.
|
||||
- **delegate_facts:** Boolean that allows you to apply facts to delegated host instead of inventory_hostname.
|
||||
- **delegate_to:** Host to execute task instead of the target (inventory_hostname), connection vars from the delegated host will also be used for the task.
|
||||
- **environment:** A dictionary that gets converted into environment vars to be provided for the task upon execution.
|
||||
- **ignore_errors:** Boolean that allows you to ignore task failures and continue with play. It does not affect connection errors.
|
||||
- **name:** It's a name, works mostly for documentation, in the case of tasks/handlers it can be an identifier.
|
||||
- **no_log:** Boolean that controls information disclosure.
|
||||
- **port:** Used to override the default port used in a connection.
|
||||
- **remote_user:** User used to log into the target via the connection plugin. AKA login user.
|
||||
- **rescue:** List of tasks in a block that run if there is a task error in the main ``block`` list.
|
||||
- **run_once:** Boolean that will bypass the host loop, forcing the task to execute on the first host available and will also apply any facts to all active hosts.
|
||||
- **tags:** Tags applied to the task or included tasks, this allows selecting subsets of tasks from the command line.
|
||||
- **vars:** Dictionary/map of variables
|
||||
- **when:** Conditional expression; determines if an iteration of a task is run or not.
|
||||
|
||||
|
||||
Task
|
||||
----
|
||||
- **action:** The 'action' to execute for a task. This normally translates into a C(module) or action plugin.
|
||||
- **always_run:** DEPRECATED. Forces a task to run even in check mode. Use check_mode directive instead.
|
||||
- **any_errors_fatal:** Force any un-handled task errors on any host to propagate to all hosts and end the play.
|
||||
- **args:** UNDOCUMENTED!!
|
||||
- **async:** Run a task asyncronouslly if the C(action) supports this.
|
||||
- **become:** Boolean that controls if privilege escalation is used or not on Task execution.
|
||||
- **become_flags:** A string of flag(s) to pass to the privilege escalation program when ``become`` is True.
|
||||
- **become_method:** Which method of privilege escalation to use (for example sudo/su/etc).
|
||||
- **become_user:** User that you 'become' after using privilege escalation. The remote/login user must have permissions to become this user.
|
||||
- **changed_when:** Conditional expression that overrides the task's normal 'changed' status.
|
||||
- **check_mode:** A boolean that controls if a task is executed in 'check' mode
|
||||
- **connection:** Allows you to change the connection plugin used for tasks to execute on the target.
|
||||
- **delay:** UNDOCUMENTED!!
|
||||
- **delegate_facts:** Boolean that allows you to apply facts to delegated host instead of inventory_hostname.
|
||||
- **delegate_to:** Host to execute task instead of the target (inventory_hostname). Connection vars from the delegated host will also be used for the task.
|
||||
- **environment:** A dictionary that gets converted into environment vars to be provided for the task upon execution.
|
||||
- **failed_when:** Conditional expression that overrides the task's normal 'failed' status.
|
||||
- **ignore_errors:** Boolean that allows you to ignore task failures and continue with play. It does not affect connection errors.
|
||||
- **local_action:** Same as action but also implies ``delegate_to: localhost``
|
||||
- **loop_control:** UNDOCUMENTED
|
||||
- **name:** It's a name, works mostly for documentation, in the case of tasks/handlers it can be an identifier.
|
||||
- **no_log:** Boolean that controls information disclosure.
|
||||
- **notify:** UNDOCUMENTED
|
||||
- **poll:** UNDOCUMENTED
|
||||
- **port:** Used to override the default port used in a connection.
|
||||
- **register:** UNDOCUMENTED!!
|
||||
- **remote_user:** User used to log into the target via the connection plugin. AKA login user.
|
||||
- **retries:** UNDOCUMENTED
|
||||
- **run_once:** Boolean that will bypass the host loop, forcing the task to execute on the first host available. This will also apply any facts to all active hosts.
|
||||
- **tags:** Tags applied to the task or included tasks. This allows selecting subsets of tasks from the command line.
|
||||
- **until:** UNDOCUMENTED
|
||||
- **vars:** Dictionary/map of variables.
|
||||
- **when:** Conditional expression; determines if an iteration of a task is run or not.
|
||||
- **with_<lookup_plugin>:** ``with_`` is how loops are defined. It can use any available lookup plugin to generate the item list.
|
||||
|
||||
@ -0,0 +1,84 @@
|
||||
Creating Reusable Playbooks
|
||||
===========================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
playbooks_reuse_includes
|
||||
playbooks_reuse_roles
|
||||
|
||||
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 allow users to break up large playbooks into 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. Roles can also be uploaded and shared via Ansible Galaxy, unlike includes and imports.
|
||||
|
||||
Dynamic vs. Static
|
||||
``````````````````
|
||||
|
||||
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 intrdouced 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 ``include`` vs. ``import``.
|
||||
|
||||
If you use any ``import*`` Task (``import_playbook``, ``import_tasks``, etc.), it will be *static*.
|
||||
If you use any ``include*`` Task (``include_tasks``, ``include_role``, etc.), it will be *dynamic*.
|
||||
|
||||
The bare ``include`` task (which was used for both Task files and Playbook-level includes) is still available, however it is now considered *deprecated*.
|
||||
|
||||
Differences Between Static and 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 conditonal 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 in-line with other tasks.
|
||||
|
||||
Tradeoffs and Pitfalls Between Includes and Imports
|
||||
```````````````````````````````````````````````````
|
||||
|
||||
Using ``include*`` vs. ``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.
|
||||
|
||||
Using ``include*`` does have some limitations when compared to ``import*`` statements:
|
||||
|
||||
* Tags which only exist inside a dynamic include will not show up in --list-tags output.
|
||||
* 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 ``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.
|
||||
|
||||
.. seealso::
|
||||
|
||||
:doc:`playbooks`
|
||||
Review the basic Playbook language features
|
||||
:doc:`playbooks_variables`
|
||||
All about variables in playbooks
|
||||
:doc:`playbooks_conditionals`
|
||||
Conditionals in playbooks
|
||||
:doc:`playbooks_loops`
|
||||
Loops in playbooks
|
||||
:doc:`playbooks_best_practices`
|
||||
Various tips about managing playbooks in the real world
|
||||
:doc:`galaxy`
|
||||
How to share roles on galaxy, role management
|
||||
`GitHub Ansible examples <https://github.com/ansible/ansible-examples>`_
|
||||
Complete playbook files from the GitHub project source
|
||||
`Mailing List <http://groups.google.com/group/ansible-project>`_
|
||||
Questions? Help? Ideas? Stop by the list on Google Groups
|
||||
|
||||
@ -0,0 +1,117 @@
|
||||
Including and Importing
|
||||
=======================
|
||||
|
||||
.. contents:: Topics
|
||||
|
||||
Includes vs. Imports
|
||||
````````````````````
|
||||
|
||||
As noted in :doc:`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 :doc:`playbooks_reuse` for documentation concerning the trade-offs one may encounter when using each type.
|
||||
|
||||
Importing Playbooks
|
||||
```````````````````
|
||||
|
||||
It is possible to include playbooks inside a master playbook. For example::
|
||||
|
||||
---
|
||||
import_playbook: webservers.yml
|
||||
import_playbook: databases.yml
|
||||
|
||||
Each playbook listed will be run in the order they are listed.
|
||||
|
||||
|
||||
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 :doc:`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 :doc:`playbooks_reuse`.
|
||||
|
||||
You can mix in includes along with your regular non-included tasks and handlers.
|
||||
|
||||
Including and Importing Roles
|
||||
`````````````````````````````
|
||||
|
||||
Please refer to :doc:`playbooks_reuse_roles` for details on including and importing roles.
|
||||
|
||||
.. seealso::
|
||||
|
||||
:doc:`YAMLSyntax`
|
||||
Learn about YAML syntax
|
||||
:doc:`playbooks`
|
||||
Review the basic Playbook language features
|
||||
:doc:`playbooks_best_practices`
|
||||
Various tips about managing playbooks in the real world
|
||||
:doc:`playbooks_variables`
|
||||
All about variables in playbooks
|
||||
:doc:`playbooks_conditionals`
|
||||
Conditionals in playbooks
|
||||
:doc:`playbooks_loops`
|
||||
Loops in playbooks
|
||||
:doc:`modules`
|
||||
Learn about available modules
|
||||
:doc:`dev_guide/developing_modules`
|
||||
Learn how to extend Ansible by writing your own modules
|
||||
`GitHub Ansible examples <https://github.com/ansible/ansible-examples>`_
|
||||
Complete playbook files from the GitHub project source
|
||||
`Mailing List <http://groups.google.com/group/ansible-project>`_
|
||||
Questions? Help? Ideas? Stop by the list on Google Groups
|
||||
|
||||
@ -0,0 +1,378 @@
|
||||
Roles
|
||||
=====
|
||||
|
||||
.. contents:: Topics
|
||||
|
||||
.. versionadded:: 1.2
|
||||
|
||||
Roles are ways of automatically loading certain vars_files, tasks, and handlers based on a known file structure. Grouping content by roles also allows easy sharing of roles with other users.
|
||||
|
||||
Role Directory Structure
|
||||
````````````````````````
|
||||
|
||||
Example project structure::
|
||||
|
||||
site.yml
|
||||
webservers.yml
|
||||
fooservers.yml
|
||||
roles/
|
||||
common/
|
||||
tasks/
|
||||
handlers/
|
||||
files/
|
||||
templates/
|
||||
vars/
|
||||
defaults/
|
||||
meta/
|
||||
webservers/
|
||||
tasks/
|
||||
defaults/
|
||||
meta/
|
||||
|
||||
Roles expect files to be in certain directory names. Roles must include at least one of these directories, however it is perfectly fine to exclude any which are not being used. When in use, each directory must contain a ``main.yml`` file, which contains the relevant content:
|
||||
|
||||
- ``tasks`` - contains the main list of tasks to be executed by the role.
|
||||
- ``handlers`` - contains handlers, which may be used by this role or even anywhere outside this role.
|
||||
- ``defaults`` - default variables for the role (see :doc:`Variables` for more information).
|
||||
- ``vars`` - other variables for the role (see :doc:`Variables` for more information).
|
||||
- ``files`` - contains files which can be deployed via this role.
|
||||
- ``templates`` - contains templates which can be deployed via this role.
|
||||
- ``meta`` - defines some meta data for this role. See below for more details.
|
||||
|
||||
Other YAML files may be included in certain directories. For example, it is common practice to have platform-specific tasks included from the ``tasks/main.yml`` file::
|
||||
|
||||
# roles/example/tasks/main.yml
|
||||
- import_tasks: redhat.yml
|
||||
when: ansible_os_platform|lower == 'redhat'
|
||||
- import_tasks: debian.yml
|
||||
when: ansible_os_platform|lower == 'debian'
|
||||
|
||||
# roles/example/tasks/redhat.yml
|
||||
- yum:
|
||||
name: "httpd"
|
||||
state: present
|
||||
|
||||
# roles/example/tasks/debian.yml
|
||||
- apt:
|
||||
name: "apache2"
|
||||
state: present
|
||||
|
||||
Roles may also include modules and other plugin types. For more information, please refer to the :doc:`Embedding Modules and Plugins In Roles` section below.
|
||||
|
||||
Using Roles
|
||||
```````````
|
||||
|
||||
The classic (original) way to use roles is via the ``roles:`` option for a given play::
|
||||
|
||||
---
|
||||
- hosts: webservers
|
||||
roles:
|
||||
- common
|
||||
- webservers
|
||||
|
||||
This designates the following behaviors, for each role 'x':
|
||||
|
||||
- If roles/x/tasks/main.yml exists, tasks listed therein will be added to the play.
|
||||
- If roles/x/handlers/main.yml exists, handlers listed therein will be added to the play.
|
||||
- If roles/x/vars/main.yml exists, variables listed therein will be added to the play.
|
||||
- If roles/x/defaults/main.yml exists, variables listed therein will be added to the play.
|
||||
- If roles/x/meta/main.yml exists, any role dependencies listed therein will be added to the list of roles (1.3 and later).
|
||||
- Any copy, script, template or include tasks (in the role) can reference files in roles/x/{files,templates,tasks}/ (dir depends on task) without having to path them relatively or absolutely.
|
||||
|
||||
When used in this manner, the order of execution for your playbook is as follows:
|
||||
|
||||
- Any ``pre_tasks`` defined in the play.
|
||||
- Any handlers triggered so far will be run.
|
||||
- Each role listed in ``roles`` will execute in turn. Any role dependencies defined in the roles ``meta/main.yml`` will be run first.
|
||||
- Any ``tasks`` defined in the play.
|
||||
- Any handlers triggered so far will be run.
|
||||
- Any ``post_tasks`` defined in the play.
|
||||
- Any handlers triggered so far will be run.
|
||||
|
||||
.. note::
|
||||
See below for more information regarding role dependencies.
|
||||
|
||||
.. note::
|
||||
If using tags with tasks (described later as a means of only running part of a playbook), be sure to also tag your pre_tasks and post_tasks and pass those along as well, especially if the pre and post tasks are used for monitoring outage window control or load balancing.
|
||||
|
||||
As of Ansible 2.4, you can now use roles inline with any other tasks using ``import_role`` or ``include_role``::
|
||||
|
||||
---
|
||||
|
||||
- hosts: webservers
|
||||
tasks:
|
||||
- debug:
|
||||
msg: "before we run our role"
|
||||
- import_role:
|
||||
name: example
|
||||
- include_role:
|
||||
name: example
|
||||
- debug:
|
||||
msg: "after we ran our role"
|
||||
|
||||
When roles are defined in the classic manner, they are treated as static imports and processed during playbook parsing.
|
||||
|
||||
.. note::
|
||||
The ``include_role`` option was introduced in Ansible 2.3. The usage has changed slightly as of Ansible 2.4 to match the include (dynamic) vs. import (static) usage. See :doc:`Dynamic vs. Static` for more details.
|
||||
|
||||
The name used for the role can be a simple name (see :doc:`Role Search Path` below), or it can be a fully qualified path::
|
||||
|
||||
---
|
||||
|
||||
- hosts: webservers
|
||||
roles:
|
||||
- { role: '/path/to/my/roles/common' }
|
||||
|
||||
Roles can accept parameters::
|
||||
|
||||
---
|
||||
|
||||
- hosts: webservers
|
||||
roles:
|
||||
- common
|
||||
- { role: foo_app_instance, dir: '/opt/a', app_port: 5000 }
|
||||
- { role: foo_app_instance, dir: '/opt/b', app_port: 5001 }
|
||||
|
||||
Or, using the newer syntax::
|
||||
|
||||
---
|
||||
|
||||
- hosts: webservers
|
||||
tasks:
|
||||
- include_role:
|
||||
name: foo_app_instance
|
||||
args:
|
||||
dir: '/opt/a'
|
||||
app_port: 5000
|
||||
...
|
||||
|
||||
You can conditionally execute a role. This is not generally recommended with the classic syntax, but is common when using ``import_role`` or ``include_role``::
|
||||
|
||||
---
|
||||
|
||||
- hosts: webservers
|
||||
tasks:
|
||||
- include_role:
|
||||
name: some_role
|
||||
when: "ansible_os_family == 'RedHat'"
|
||||
|
||||
Finally, you may wish to assign tags to the roles you specify. You can do so inline::
|
||||
|
||||
---
|
||||
|
||||
- hosts: webservers
|
||||
roles:
|
||||
- { role: foo, tags: ["bar", "baz"] }
|
||||
|
||||
Or, again, using the newer syntax::
|
||||
|
||||
---
|
||||
|
||||
- hosts: webservers
|
||||
tasks:
|
||||
- import_role:
|
||||
name: foo
|
||||
tags:
|
||||
- bar
|
||||
- baz
|
||||
|
||||
.. note::
|
||||
This *tags all of the tasks in that role with the tags specified*, overriding any tags that are specified inside the role. If you find yourself building a role with lots of tags and you want to call subsets of the role at different times, you should consider just splitting that role into multiple roles.
|
||||
|
||||
Role Duplication and Execution
|
||||
``````````````````````````````
|
||||
|
||||
Ansible will only allow a role to execute once, even if defined multiple times, if the parameters defined on the role are not different for each definition. For example::
|
||||
|
||||
---
|
||||
- hosts: webservers
|
||||
roles:
|
||||
- foo
|
||||
- foo
|
||||
|
||||
Given the above, the role ``foo`` will only be run once.
|
||||
|
||||
To make roles run more than once, there are two options:
|
||||
|
||||
1. Pass different parameters in each role definition.
|
||||
2. Add ``allow_duplicates: true`` to the ``meta/main.yml`` file for the role.
|
||||
|
||||
Example 1 - passing different paramters::
|
||||
|
||||
---
|
||||
- hosts: webservers
|
||||
roles:
|
||||
- { role: foo, message: "first" }
|
||||
- { role: foo, message: "second" }
|
||||
|
||||
In this example, because each role definition has different parameters, ``foo`` will run twice.
|
||||
|
||||
Example 2 - using ``allow_duplicates: true``::
|
||||
|
||||
# playbook.yml
|
||||
---
|
||||
- hosts: webservers
|
||||
roles:
|
||||
- foo
|
||||
- foo
|
||||
|
||||
# roles/foo/meta/main.yml
|
||||
---
|
||||
allow_duplicates: true
|
||||
|
||||
In this example, ``foo`` will run twice because we have explicitly enabled it to do so.
|
||||
|
||||
Role Default Variables
|
||||
``````````````````````
|
||||
|
||||
.. versionadded:: 1.3
|
||||
|
||||
Role default variables allow you to set default variables for included or dependent roles (see below). To create
|
||||
defaults, simply add a ``defaults/main.yml`` file in your role directory. These variables will have the lowest priority
|
||||
of any variables available, and can be easily overridden by any other variable, including inventory variables.
|
||||
|
||||
Role Dependencies
|
||||
`````````````````
|
||||
|
||||
.. versionadded:: 1.3
|
||||
|
||||
Role dependencies allow you to automatically pull in other roles when using a role. Role dependencies are stored in the ``meta/main.yml`` file contained within the role directory, as noted above. This file should contain a list of roles and parameters to insert before the specified role, such as the following in an example ``roles/myapp/meta/main.yml``::
|
||||
|
||||
---
|
||||
dependencies:
|
||||
- { role: common, some_parameter: 3 }
|
||||
- { role: apache, apache_port: 80 }
|
||||
- { role: postgres, dbname: blarg, other_parameter: 12 }
|
||||
|
||||
.. note::
|
||||
Role dependencies must use the classic role definition style.
|
||||
|
||||
Role dependencies are always executed before the role that includes them, and may be recursive. Dependencies also follow the duplication rules specified above. If another role also lists it as a dependency, it will not be run again based on the same rules given above.
|
||||
|
||||
.. note::
|
||||
Always remember that when using ``allow_duplicates: true``, it needs to be in the dependent role's ``meta/main.yml``, not the parent.
|
||||
|
||||
For example, a role named ``car`` depends on a role named ``wheel`` as follows::
|
||||
|
||||
---
|
||||
dependencies:
|
||||
- { role: wheel, n: 1 }
|
||||
- { role: wheel, n: 2 }
|
||||
- { role: wheel, n: 3 }
|
||||
- { role: wheel, n: 4 }
|
||||
|
||||
And the ``wheel`` role depends on two roles: ``tire`` and ``brake``. The ``meta/main.yml`` for wheel would then contain the following::
|
||||
|
||||
---
|
||||
dependencies:
|
||||
- { role: tire }
|
||||
- { role: brake }
|
||||
|
||||
And the ``meta/main.yml`` for ``tire`` and ``brake`` would contain the following::
|
||||
|
||||
---
|
||||
allow_duplicates: true
|
||||
|
||||
|
||||
The resulting order of execution would be as follows::
|
||||
|
||||
tire(n=1)
|
||||
brake(n=1)
|
||||
wheel(n=1)
|
||||
tire(n=2)
|
||||
brake(n=2)
|
||||
wheel(n=2)
|
||||
...
|
||||
car
|
||||
|
||||
Note that we did not have to use ``allow_duplicates: true`` for ``wheel``, because each instance defined by ``car`` uses different parameter values.
|
||||
|
||||
.. note::
|
||||
Variable inheritance and scope are detailed in the :doc:`playbooks_variables`.
|
||||
|
||||
Embedding Modules and Plugins In Roles
|
||||
``````````````````````````````````````
|
||||
|
||||
This is an advanced topic that should not be relevant for most users.
|
||||
|
||||
If you write a custom module (see :doc:`dev_guide/developing_modules`) or a plugin (see :doc:`dev_guide/developing_plugins`), you may wish to distribute it as part of a role.
|
||||
Generally speaking, Ansible as a project is very interested in taking high-quality modules into ansible core for inclusion, so this shouldn't be the norm, but it's quite easy to do.
|
||||
|
||||
A good example for this is if you worked at a company called AcmeWidgets, and wrote an internal module that helped configure your internal software, and you wanted other
|
||||
people in your organization to easily use this module -- but you didn't want to tell everyone how to configure their Ansible library path.
|
||||
|
||||
Alongside the 'tasks' and 'handlers' structure of a role, add a directory named 'library'. In this 'library' directory, then include the module directly inside of it.
|
||||
|
||||
Assuming you had this::
|
||||
|
||||
roles/
|
||||
my_custom_modules/
|
||||
library/
|
||||
module1
|
||||
module2
|
||||
|
||||
The module will be usable in the role itself, as well as any roles that are called *after* this role, as follows::
|
||||
|
||||
|
||||
- hosts: webservers
|
||||
roles:
|
||||
- my_custom_modules
|
||||
- some_other_role_using_my_custom_modules
|
||||
- yet_another_role_using_my_custom_modules
|
||||
|
||||
This can also be used, with some limitations, to modify modules in Ansible's core distribution, such as to use development versions of modules before they are released in production releases. This is not always advisable as API signatures may change in core components, however, and is not always guaranteed to work. It can be a handy way of carrying a patch against a core module, however, should you have good reason for this. Naturally the project prefers that contributions be directed back to github whenever possible via a pull request.
|
||||
|
||||
The same mechanism can be used to embed and distribute plugins in a role, using the same schema. For example, for a filter plugin::
|
||||
|
||||
roles/
|
||||
my_custom_filter/
|
||||
filter_plugins
|
||||
filter1
|
||||
filter2
|
||||
|
||||
They can then be used in a template or a jinja template in any role called after 'my_custom_filter'
|
||||
|
||||
Role Search Path
|
||||
````````````````
|
||||
|
||||
Ansible will search for roles in the following way:
|
||||
|
||||
- A ``roles/`` directory, relative to the playbook file.
|
||||
- By default, in ``/etc/ansible/roles``
|
||||
|
||||
In Ansible 1.4 and later you can configure an additional roles_path to search for roles. Use this to check all of your common roles out to one location, and share them easily between multiple playbook projects. See :doc:`intro_configuration` for details about how to set this up in ansible.cfg.
|
||||
|
||||
Ansible Galaxy
|
||||
``````````````
|
||||
|
||||
`Ansible Galaxy <https://galaxy.ansible.com>`_ is a free site for finding, downloading, rating, and reviewing all kinds of community developed Ansible roles and can be a great way to get a jumpstart on your automation projects.
|
||||
|
||||
You can sign up with social auth, and the download client 'ansible-galaxy' is included in Ansible 1.4.2 and later.
|
||||
|
||||
Read the "About" page on the Galaxy site for more information.
|
||||
|
||||
.. seealso::
|
||||
|
||||
:doc:`galaxy`
|
||||
How to share roles on galaxy, role management
|
||||
:doc:`YAMLSyntax`
|
||||
Learn about YAML syntax
|
||||
:doc:`playbooks`
|
||||
Review the basic Playbook language features
|
||||
:doc:`playbooks_best_practices`
|
||||
Various tips about managing playbooks in the real world
|
||||
:doc:`playbooks_variables`
|
||||
All about variables in playbooks
|
||||
:doc:`playbooks_conditionals`
|
||||
Conditionals in playbooks
|
||||
:doc:`playbooks_loops`
|
||||
Loops in playbooks
|
||||
:doc:`modules`
|
||||
Learn about available modules
|
||||
:doc:`dev_guide/developing_modules`
|
||||
Learn how to extend Ansible by writing your own modules
|
||||
`GitHub Ansible examples <https://github.com/ansible/ansible-examples>`_
|
||||
Complete playbook files from the GitHub project source
|
||||
`Mailing List <http://groups.google.com/group/ansible-project>`_
|
||||
Questions? Help? Ideas? Stop by the list on Google Groups
|
||||
|
||||
Loading…
Reference in New Issue