From f4ad1c771e31d857df7b86f2c78bcd4ababb6f8c Mon Sep 17 00:00:00 2001 From: Sandra McCann Date: Wed, 15 Jun 2022 09:08:27 -0400 Subject: [PATCH] Create reusable role layout snippet for documentation (#78057) * reuse role structure * reuse role snippet in role docs --- .../rst/user_guide/playbooks_reuse_roles.rst | 16 ++--------- docs/docsite/rst/user_guide/sample_setup.rst | 28 ++----------------- .../shared_snippets/role_directory.txt | 26 +++++++++++++++++ 3 files changed, 30 insertions(+), 40 deletions(-) create mode 100644 docs/docsite/rst/user_guide/shared_snippets/role_directory.txt diff --git a/docs/docsite/rst/user_guide/playbooks_reuse_roles.rst b/docs/docsite/rst/user_guide/playbooks_reuse_roles.rst index 74208d56480..30e96a75753 100644 --- a/docs/docsite/rst/user_guide/playbooks_reuse_roles.rst +++ b/docs/docsite/rst/user_guide/playbooks_reuse_roles.rst @@ -20,20 +20,8 @@ An Ansible role has a defined directory structure with eight main standard direc site.yml webservers.yml fooservers.yml - roles/ - common/ - tasks/ - handlers/ - library/ - files/ - templates/ - vars/ - defaults/ - meta/ - webservers/ - tasks/ - defaults/ - meta/ +.. include:: shared_snippets/role_directory.txt + By default Ansible will look in each directory within a role for a ``main.yml`` file for relevant content (also ``main.yaml`` and ``main``): diff --git a/docs/docsite/rst/user_guide/sample_setup.rst b/docs/docsite/rst/user_guide/sample_setup.rst index db21a18818b..1f267a72c75 100644 --- a/docs/docsite/rst/user_guide/sample_setup.rst +++ b/docs/docsite/rst/user_guide/sample_setup.rst @@ -16,7 +16,7 @@ Sample directory layout This layout organizes most tasks in roles, with a single inventory file for each environment and a few playbooks in the top-level directory: - .. code-block:: console +.. code-block:: console production # inventory file for production servers staging # inventory file for staging environment @@ -37,31 +37,7 @@ This layout organizes most tasks in roles, with a single inventory file for each dbservers.yml # playbook for dbserver tier tasks/ # task files included from playbooks webservers-extra.yml # <-- avoids confusing playbook with task files - - roles/ - common/ # this hierarchy represents a "role" - tasks/ # - main.yml # <-- tasks file can include smaller files if warranted - handlers/ # - main.yml # <-- handlers file - templates/ # <-- files for use with the template resource - ntp.conf.j2 # <------- templates end in .j2 - files/ # - bar.txt # <-- files for use with the copy resource - foo.sh # <-- script files for use with the script resource - vars/ # - main.yml # <-- variables associated with this role - defaults/ # - main.yml # <-- default lower priority variables for this role - meta/ # - main.yml # <-- role dependencies - library/ # roles can also include custom modules - module_utils/ # roles can also include custom module_utils - lookup_plugins/ # or other types of plugins, like lookup in this case - - webtier/ # same kind of structure as "common" was above, done for the webtier role - monitoring/ # "" - fooapp/ # "" +.. include:: shared_snippets/role_directory.txt .. note:: By default, Ansible assumes your playbooks are stored in one directory with roles stored in a sub-directory called ``roles/``. As you use Ansible to automate more tasks, you may want to move your playbooks into a sub-directory called ``playbooks/``. If you do this, you must configure the path to your ``roles/`` directory using the ``roles_path`` setting in ansible.cfg. diff --git a/docs/docsite/rst/user_guide/shared_snippets/role_directory.txt b/docs/docsite/rst/user_guide/shared_snippets/role_directory.txt new file mode 100644 index 00000000000..5722f0ee894 --- /dev/null +++ b/docs/docsite/rst/user_guide/shared_snippets/role_directory.txt @@ -0,0 +1,26 @@ +.. code-block:: yaml + + roles/ + common/ # this hierarchy represents a "role" + tasks/ # + main.yml # <-- tasks file can include smaller files if warranted + handlers/ # + main.yml # <-- handlers file + templates/ # <-- files for use with the template resource + ntp.conf.j2 # <------- templates end in .j2 + files/ # + bar.txt # <-- files for use with the copy resource + foo.sh # <-- script files for use with the script resource + vars/ # + main.yml # <-- variables associated with this role + defaults/ # + main.yml # <-- default lower priority variables for this role + meta/ # + main.yml # <-- role dependencies + library/ # roles can also include custom modules + module_utils/ # roles can also include custom module_utils + lookup_plugins/ # or other types of plugins, like lookup in this case + + webtier/ # same kind of structure as "common" was above, done for the webtier role + monitoring/ # "" + fooapp/ # ""