Cleaning up use of include: in docs (#30466)

* Cleaning up use of include: in docs

Switching to import_*/include_* instead.

* Update playbooks_best_practices.rst

* Fix rst syntax
pull/30474/head
James Cammarata 7 years ago committed by scottb
parent 2a42ed520b
commit 366a9d861f

@ -152,7 +152,7 @@ Content of the *requirements.yml* file:
# from galaxy # from galaxy
- src: yatesr.timezone - src: yatesr.timezone
- include: <path_to_requirements>/webserver.yml - import_tasks: <path_to_requirements>/webserver.yml
Content of the *webserver.yml* file: Content of the *webserver.yml* file:

@ -94,7 +94,7 @@ of tasks running concurrently, you can do it this way::
- 4 - 4
- 5 - 5
durations: "{{ item }}" durations: "{{ item }}"
include: execute_batch.yml include_tasks: execute_batch.yml
with_items: with_items:
- "{{ sleep_durations | batch(2) | list }}" - "{{ sleep_durations | batch(2) | list }}"

@ -216,15 +216,15 @@ variables from the file "group_vars/ec2_tag_class_webserver" automatically.
Top Level Playbooks Are Separated By Role Top Level Playbooks Are Separated By Role
````````````````````````````````````````` `````````````````````````````````````````
In site.yml, we include a playbook that defines our entire infrastructure. Note this is SUPER short, because it's just including In site.yml, we import a playbook that defines our entire infrastructure. This is a very short example, because it's just importing
some other playbooks. Remember, playbooks are nothing more than lists of plays:: some other playbooks::
--- ---
# file: site.yml # file: site.yml
- include: webservers.yml - import_plays: webservers.yml
- include: dbservers.yml - import_plays: dbservers.yml
In a file like webservers.yml (also at the top level), we simply map the configuration of the webservers group to the roles performed by the webservers group. Also notice this is incredibly short. For example:: In a file like webservers.yml (also at the top level), we map the configuration of the webservers group to the roles performed by the webservers group::
--- ---
# file: webservers.yml # file: webservers.yml

@ -154,13 +154,13 @@ there will be accessible to future tasks::
.. _when_roles_and_includes: .. _when_roles_and_includes:
Applying 'when' to roles and includes Applying 'when' to roles, imports, and includes
````````````````````````````````````` ```````````````````````````````````````````````
Note that if you have several tasks that all share the same conditional statement, you can affix the conditional Note that if you have several tasks that all share the same conditional statement, you can affix the conditional
to a task include statement as below. All the tasks get evaluated, but the conditional is applied to each and every task:: to a task include statement as below. All the tasks get evaluated, but the conditional is applied to each and every task::
- include: tasks/sometasks.yml - import_tasks: tasks/sometasks.yml
when: "'reticulating splines' in output" when: "'reticulating splines' in output"
.. note:: In versions prior to 2.0 this worked with task includes but not playbook includes. 2.0 allows it to work with both. .. note:: In versions prior to 2.0 this worked with task includes but not playbook includes. 2.0 allows it to work with both.
@ -174,6 +174,24 @@ Or with a role::
You will note a lot of 'skipped' output by default in Ansible when using this approach on systems that don't match the criteria. You will note a lot of 'skipped' output by default in Ansible when using this approach on systems that don't match the criteria.
Read up on the 'group_by' module in the :doc:`modules` docs for a more streamlined way to accomplish the same thing. Read up on the 'group_by' module in the :doc:`modules` docs for a more streamlined way to accomplish the same thing.
When used with `include_*` tasks instead of imports, the conditional is applied _only_ to the include task itself and not any other
tasks within the included file(s). A common situation where this distinction is important is as follows::
# include a file to define a variable when it is not already defined
# main.yml
- include_tasks: other_tasks.yml
when: x is not defined
# other_tasks.yml
- set_fact:
x: foo
- debug:
var: x
In the above example, if ``import_tasks`` had been used instead both included tasks would have also been skipped. With ``include_tasks``
instead, the tasks are executed as expected because the conditional is not applied to them.
.. _conditional_imports: .. _conditional_imports:
Conditional Imports Conditional Imports

@ -359,7 +359,7 @@ a variable called ``vhost`` in the ``vars`` section, you could do this::
Those same variables are usable in templates, which we'll get to later. Those same variables are usable in templates, which we'll get to later.
Now in a very basic playbook all the tasks will be listed directly in that play, though it will usually Now in a very basic playbook all the tasks will be listed directly in that play, though it will usually
make more sense to break up tasks using the ``include:`` directive. We'll show that a bit later. make more sense to break up tasks as described in :doc:`playbooks_reuse`.
.. _action_shorthand: .. _action_shorthand:

@ -743,7 +743,7 @@ Ansible by default sets the loop variable `item` for each loop, which causes the
As of Ansible 2.1, the `loop_control` option can be used to specify the name of the variable to be used for the loop:: As of Ansible 2.1, the `loop_control` option can be used to specify the name of the variable to be used for the loop::
# main.yml # main.yml
- include: inner.yml - include_tasks: inner.yml
with_items: with_items:
- 1 - 1
- 2 - 2
@ -807,7 +807,7 @@ Because `loop_control` is not available in Ansible 2.0, when using an include wi
for `item`:: for `item`::
# main.yml # main.yml
- include: inner.yml - include_tasks: inner.yml
with_items: with_items:
- 1 - 1
- 2 - 2

@ -80,9 +80,14 @@ You may also apply tags to roles::
roles: roles:
- { role: webserver, port: 5000, tags: [ 'web', 'foo' ] } - { role: webserver, port: 5000, tags: [ 'web', 'foo' ] }
And include statements:: And import/include statements::
- include: foo.yml - import_tasks: foo.yml
tags: [web,foo]
or::
- include_tasks: foo.yml
tags: [web,foo] tags: [web,foo]
All of these apply the specified tags to EACH task inside the play, included All of these apply the specified tags to EACH task inside the play, included

@ -138,12 +138,12 @@ While all items listed here will show a deprecation warning message, they still
* Specifying variables at the top level of a task include statement is no longer supported. For example:: * Specifying variables at the top level of a task include statement is no longer supported. For example::
- include: foo.yml - include_tasks: foo.yml
a: 1 a: 1
Should now be:: Should now be::
- include: foo.yml - include_tasks: foo.yml
vars: vars:
a: 1 a: 1
@ -152,11 +152,11 @@ Should now be::
* Tags (or any directive) should no longer be specified with other parameters in a task include. Instead, they should be specified as an option on the task. * Tags (or any directive) should no longer be specified with other parameters in a task include. Instead, they should be specified as an option on the task.
For example:: For example::
- include: foo.yml tags=a,b,c - include_tasks: foo.yml tags=a,b,c
Should be:: Should be::
- include: foo.yml - include_tasks: foo.yml
tags: [a, b, c] tags: [a, b, c]
* The first_available_file option on tasks has been deprecated. Users should use the with_first_found option or lookup (first_found, …) plugin. * The first_available_file option on tasks has been deprecated. Users should use the with_first_found option or lookup (first_found, …) plugin.

Loading…
Cancel
Save