From f4fff54f6804885f5b203406a614d07b331cc646 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. --- 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 f715ca92f7..ade1ab11e0 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 98e934ba9d..d4fca33802 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 -Each playbook listed will be run in the order they are listed. +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 `````````````````````````````````` diff --git a/docs/docsite/rst/playbooks_reuse_roles.rst b/docs/docsite/rst/playbooks_reuse_roles.rst index af41407132..f019376319 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'