From 366a9d861f68baee0991f450289d060d382a980b Mon Sep 17 00:00:00 2001 From: James Cammarata Date: Sun, 17 Sep 2017 13:02:46 -0500 Subject: [PATCH] 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 --- docs/docsite/rst/galaxy.rst | 2 +- docs/docsite/rst/playbooks_async.rst | 2 +- docs/docsite/rst/playbooks_best_practices.rst | 10 ++++---- docs/docsite/rst/playbooks_conditionals.rst | 24 ++++++++++++++++--- docs/docsite/rst/playbooks_intro.rst | 2 +- docs/docsite/rst/playbooks_loops.rst | 4 ++-- docs/docsite/rst/playbooks_tags.rst | 9 +++++-- docs/docsite/rst/porting_guide_2.0.rst | 8 +++---- 8 files changed, 42 insertions(+), 19 deletions(-) diff --git a/docs/docsite/rst/galaxy.rst b/docs/docsite/rst/galaxy.rst index a0028be2e99..728898caead 100644 --- a/docs/docsite/rst/galaxy.rst +++ b/docs/docsite/rst/galaxy.rst @@ -152,7 +152,7 @@ Content of the *requirements.yml* file: # from galaxy - src: yatesr.timezone - - include: /webserver.yml + - import_tasks: /webserver.yml Content of the *webserver.yml* file: diff --git a/docs/docsite/rst/playbooks_async.rst b/docs/docsite/rst/playbooks_async.rst index 60fe8c46343..026c006e871 100644 --- a/docs/docsite/rst/playbooks_async.rst +++ b/docs/docsite/rst/playbooks_async.rst @@ -94,7 +94,7 @@ of tasks running concurrently, you can do it this way:: - 4 - 5 durations: "{{ item }}" - include: execute_batch.yml + include_tasks: execute_batch.yml with_items: - "{{ sleep_durations | batch(2) | list }}" diff --git a/docs/docsite/rst/playbooks_best_practices.rst b/docs/docsite/rst/playbooks_best_practices.rst index 3939e38c3a3..aab4d114b1f 100644 --- a/docs/docsite/rst/playbooks_best_practices.rst +++ b/docs/docsite/rst/playbooks_best_practices.rst @@ -216,15 +216,15 @@ variables from the file "group_vars/ec2_tag_class_webserver" automatically. 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 -some other playbooks. Remember, playbooks are nothing more than lists of plays:: +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:: --- # file: site.yml - - include: webservers.yml - - include: dbservers.yml + - import_plays: webservers.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 diff --git a/docs/docsite/rst/playbooks_conditionals.rst b/docs/docsite/rst/playbooks_conditionals.rst index e4875d6cb93..f79c82c06e6 100644 --- a/docs/docsite/rst/playbooks_conditionals.rst +++ b/docs/docsite/rst/playbooks_conditionals.rst @@ -154,13 +154,13 @@ there will be accessible to future tasks:: .. _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 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" .. 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. 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 diff --git a/docs/docsite/rst/playbooks_intro.rst b/docs/docsite/rst/playbooks_intro.rst index 0b766af4a27..15b8e55022a 100644 --- a/docs/docsite/rst/playbooks_intro.rst +++ b/docs/docsite/rst/playbooks_intro.rst @@ -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. 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: diff --git a/docs/docsite/rst/playbooks_loops.rst b/docs/docsite/rst/playbooks_loops.rst index 515630f5eca..44b3c2f3fc1 100644 --- a/docs/docsite/rst/playbooks_loops.rst +++ b/docs/docsite/rst/playbooks_loops.rst @@ -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:: # main.yml - - include: inner.yml + - include_tasks: inner.yml with_items: - 1 - 2 @@ -807,7 +807,7 @@ Because `loop_control` is not available in Ansible 2.0, when using an include wi for `item`:: # main.yml - - include: inner.yml + - include_tasks: inner.yml with_items: - 1 - 2 diff --git a/docs/docsite/rst/playbooks_tags.rst b/docs/docsite/rst/playbooks_tags.rst index d8dac984099..0867eaa5bda 100644 --- a/docs/docsite/rst/playbooks_tags.rst +++ b/docs/docsite/rst/playbooks_tags.rst @@ -80,9 +80,14 @@ You may also apply tags to roles:: roles: - { 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] All of these apply the specified tags to EACH task inside the play, included diff --git a/docs/docsite/rst/porting_guide_2.0.rst b/docs/docsite/rst/porting_guide_2.0.rst index 9919a4707c3..c8774663b7d 100644 --- a/docs/docsite/rst/porting_guide_2.0.rst +++ b/docs/docsite/rst/porting_guide_2.0.rst @@ -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:: - - include: foo.yml + - include_tasks: foo.yml a: 1 Should now be:: - - include: foo.yml + - include_tasks: foo.yml vars: 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. For example:: - - include: foo.yml tags=a,b,c + - include_tasks: foo.yml tags=a,b,c Should be:: - - include: foo.yml + - include_tasks: foo.yml 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.