From 18fdc34ecf89ef9f9de02bc0315569a3d7f4e81e Mon Sep 17 00:00:00 2001 From: Brian Coca Date: Wed, 6 Sep 2017 23:50:50 -0400 Subject: [PATCH] clarify import_ docs (#28395) * clarify import_ docs * fixed izpellz * Copy edits. (cherry picked from commit f4fff54f6804885f5b203406a614d07b331cc646) --- docs/docsite/rst/playbooks_reuse.rst | 2 +- docs/docsite/rst/playbooks_reuse_includes.rst | 14 +++++++++++--- docs/docsite/rst/playbooks_reuse_roles.rst | 3 ++- 3 files changed, 14 insertions(+), 5 deletions(-) diff --git a/docs/docsite/rst/playbooks_reuse.rst b/docs/docsite/rst/playbooks_reuse.rst index f715ca92f7a..ade1ab11e07 100644 --- a/docs/docsite/rst/playbooks_reuse.rst +++ b/docs/docsite/rst/playbooks_reuse.rst @@ -9,7 +9,7 @@ Creating Reusable Playbooks 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 smaller files, which can be used across multiple parent playbooks or even multiple times within the same Playbook. +Includes and imports (added in 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. diff --git a/docs/docsite/rst/playbooks_reuse_includes.rst b/docs/docsite/rst/playbooks_reuse_includes.rst index 98e934ba9da..d4fca338023 100644 --- a/docs/docsite/rst/playbooks_reuse_includes.rst +++ b/docs/docsite/rst/playbooks_reuse_includes.rst @@ -13,17 +13,25 @@ As noted in :doc:`playbooks_reuse`, include and import statements are very simil 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 + - 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. -Each playbook listed will be run in the order they are listed. +.. versionadded:: 2.4 Including and Importing Task Files `````````````````````````````````` diff --git a/docs/docsite/rst/playbooks_reuse_roles.rst b/docs/docsite/rst/playbooks_reuse_roles.rst index af41407132e..f0193763198 100644 --- a/docs/docsite/rst/playbooks_reuse_roles.rst +++ b/docs/docsite/rst/playbooks_reuse_roles.rst @@ -42,7 +42,8 @@ Roles expect files to be in certain directory names. Roles must include at least 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 + - name: added in 2.4, previouslly you used 'include' + import_tasks: redhat.yml when: ansible_os_platform|lower == 'redhat' - import_tasks: debian.yml when: ansible_os_platform|lower == 'debian'