From d6063b7457086a2ed04899c47d1fc6ee4d654de9 Mon Sep 17 00:00:00 2001 From: Sandra McCann Date: Thu, 24 Sep 2020 10:45:11 -0400 Subject: [PATCH] clarify FQCN use for playbooks (#71816) * clarify FQCN use * Apply suggestions from code review Co-authored-by: Alicia Cozine <879121+acozine@users.noreply.github.com> Co-authored-by: Alicia Cozine <879121+acozine@users.noreply.github.com> --- .../rst/user_guide/collections_using.rst | 2 +- .../rst/user_guide/playbooks_intro.rst | 24 +++++++++++-------- 2 files changed, 15 insertions(+), 11 deletions(-) diff --git a/docs/docsite/rst/user_guide/collections_using.rst b/docs/docsite/rst/user_guide/collections_using.rst index a9530a9e1d0..78ae2b61cac 100644 --- a/docs/docsite/rst/user_guide/collections_using.rst +++ b/docs/docsite/rst/user_guide/collections_using.rst @@ -274,7 +274,7 @@ Simplifying module names with the ``collections`` keyword The ``collections`` keyword lets you define a list of collections that your role or playbook should search for unqualified module and action names. So you can use the ``collections`` keyword, then simply refer to modules and action plugins by their short-form names throughout that role or playbook. .. warning:: - If your playbook uses both the ``collections`` keyword and one or more roles, the roles do not inherit the collections set by the playbook. See below for details. + If your playbook uses both the ``collections`` keyword and one or more roles, the roles do not inherit the collections set by the playbook. This is one of the reasons we recommend you always use FQCN. See below for roles details. Using ``collections`` in roles ------------------------------ diff --git a/docs/docsite/rst/user_guide/playbooks_intro.rst b/docs/docsite/rst/user_guide/playbooks_intro.rst index 24037b3ed85..10334076fb5 100644 --- a/docs/docsite/rst/user_guide/playbooks_intro.rst +++ b/docs/docsite/rst/user_guide/playbooks_intro.rst @@ -33,34 +33,38 @@ A playbook runs in order from top to bottom. Within each play, tasks also run in * the managed nodes to target, using a :ref:`pattern ` * at least one task to execute +.. note:: + + In Ansible 2.10 and later, we recommend you use the fully-qualified collection name in your playbooks to ensure the correct module is selected, because multiple collections can contain modules with the same name (for example, ``user``). See :ref:`collections_using_playbook`. + In this example, the first play targets the web servers; the second play targets the database servers:: --- - - name: update web servers + - name: Update web servers hosts: webservers remote_user: root tasks: - - name: ensure apache is at the latest version - yum: + - name: Ensure apache is at the latest version + ansible.builtin.yum: name: httpd state: latest - - name: write the apache config file - template: + - name: Write the apache config file + ansible.builtin.template: src: /srv/httpd.j2 dest: /etc/httpd.conf - - name: update db servers + - name: Update db servers hosts: databases remote_user: root tasks: - - name: ensure postgresql is at the latest version - yum: + - name: Ensure postgresql is at the latest version + ansible.builtin.yum: name: postgresql state: latest - - name: ensure that postgresql is started - service: + - name: Ensure that postgresql is started + ansible.builtin.service: name: postgresql state: started