8998ec17b8
* Docs refactor as outlined in https://github.com/ansible/proposals/issues/79. Moves content into 'guides'; refactors TOC; fixes CSS; design tweaks to layout and CSS; fixes generated plugin, CLI and module docs to fix links accodingly; more.
* Adding extra blank line for shippable
(cherry picked from commit 373b1dcf59)
131 lines
4.4 KiB
ReStructuredText
131 lines
4.4 KiB
ReStructuredText
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.
|
|
|
|
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.
|
|
|
|
.. versionadded:: 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.
|
|
|
|
|
|
.. versionadded:: 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
|
|
vars:
|
|
wp_user: timmy
|
|
- import_tasks: wordpress.yml
|
|
vars:
|
|
wp_user: alice
|
|
- import_tasks: wordpress.yml
|
|
vars:
|
|
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 :ref:`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 :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
|
|
|