From 2a3aa66fbd2a41a64048f75658080783ce3525be Mon Sep 17 00:00:00 2001 From: marie Date: Tue, 12 Oct 2021 07:21:30 -0400 Subject: [PATCH] docs - wrap examples in code-block:: in sample setup (#75964) * docs: Use code-block to format code in sample setup Fixes #75905 Co-authored-by: Abhijeet Kasurde --- docs/docsite/rst/user_guide/sample_setup.rst | 72 +++++++++++++++----- 1 file changed, 54 insertions(+), 18 deletions(-) diff --git a/docs/docsite/rst/user_guide/sample_setup.rst b/docs/docsite/rst/user_guide/sample_setup.rst index 9142862db9b..db21a18818b 100644 --- a/docs/docsite/rst/user_guide/sample_setup.rst +++ b/docs/docsite/rst/user_guide/sample_setup.rst @@ -14,7 +14,9 @@ The sample setup organizes playbooks, roles, inventory, and variables files by f 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:: +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 production # inventory file for production servers staging # inventory file for staging environment @@ -66,7 +68,9 @@ This layout organizes most tasks in roles, with a single inventory file for each Alternative directory layout ---------------------------- -Alternatively you can put each inventory file with its ``group_vars``/``host_vars`` in a separate directory. This is particularly useful if your ``group_vars``/``host_vars`` don't have that much in common in different environments. The layout could look something like this:: +Alternatively you can put each inventory file with its ``group_vars``/``host_vars`` in a separate directory. This is particularly useful if your ``group_vars``/``host_vars`` don't have that much in common in different environments. The layout could look something like this: + + .. code-block:: console inventories/ production/ @@ -108,28 +112,36 @@ This layout gives you more flexibility for larger environments, as well as a tot Sample group and host variables ------------------------------- -These sample group and host variables files record the variable values that apply to each machine or group of machines. For instance, the data center in Atlanta has its own NTP servers, so when setting up ntp.conf, we should use them:: +These sample group and host variables files record the variable values that apply to each machine or group of machines. For instance, the data center in Atlanta has its own NTP servers, so when setting up ntp.conf, we should use them: + + .. code-block:: yaml --- # file: group_vars/atlanta ntp: ntp-atlanta.example.com backup: backup-atlanta.example.com -Similarly, the webservers have some configuration that does not apply to the database servers:: +Similarly, the webservers have some configuration that does not apply to the database servers: + + .. code-block:: yaml --- # file: group_vars/webservers apacheMaxRequestsPerChild: 3000 apacheMaxClients: 900 -Default values, or values that are universally true, belong in a file called group_vars/all:: +Default values, or values that are universally true, belong in a file called group_vars/all: + + .. code-block:: yaml --- # file: group_vars/all ntp: ntp-boston.example.com backup: backup-boston.example.com -If necessary, you can define specific hardware variance in systems in a host_vars file:: +If necessary, you can define specific hardware variance in systems in a host_vars file: + + .. code-block:: yaml --- # file: host_vars/db-bos-1.example.com @@ -143,14 +155,18 @@ Again, if you are using :ref:`dynamic inventory `, Ansible cr Sample playbooks organized by function -------------------------------------- -With this setup, a single playbook can define all the infrastructure. The site.yml playbook imports two other playbooks, one for the webservers and one for the database servers:: +With this setup, a single playbook can define all the infrastructure. The site.yml playbook imports two other playbooks, one for the webservers and one for the database servers: + + .. code-block:: yaml --- # file: site.yml - import_playbook: webservers.yml - import_playbook: dbservers.yml -The webservers.yml file, also at the top level, maps the configuration of the webservers group to the roles related to the webservers group:: +The webservers.yml file, also at the top level, maps the configuration of the webservers group to the roles related to the webservers group: + + .. code-block:: yaml --- # file: webservers.yml @@ -159,7 +175,9 @@ The webservers.yml file, also at the top level, maps the configuration of the we - common - webtier -With this setup, you can configure your whole infrastructure by "running" site.yml, or run a subset by running webservers.yml. This is analogous to the Ansible "--limit" parameter but a little more explicit:: +With this setup, you can configure your whole infrastructure by "running" site.yml, or run a subset by running webservers.yml. This is analogous to the Ansible "--limit" parameter but a little more explicit: + + .. code-block:: shell ansible-playbook site.yml --limit webservers ansible-playbook webservers.yml @@ -169,7 +187,9 @@ With this setup, you can configure your whole infrastructure by "running" site.y Sample task and handler files in a function-based role ------------------------------------------------------ -Ansible loads any file called ``main.yml`` in a role sub-directory. This sample ``tasks/main.yml`` file is simple - it sets up NTP, but it could do more if we wanted:: +Ansible loads any file called ``main.yml`` in a role sub-directory. This sample ``tasks/main.yml`` file is simple - it sets up NTP, but it could do more if we wanted: + + .. code-block:: yaml --- # file: roles/common/tasks/main.yml @@ -196,7 +216,9 @@ Ansible loads any file called ``main.yml`` in a role sub-directory. This sample tags: ntp Here is an example handlers file. As a review, handlers are only fired when certain tasks report changes, and are run at the end -of each play:: +of each play: + + .. code-block:: yaml --- # file: roles/common/handlers/main.yml @@ -213,33 +235,47 @@ See :ref:`playbooks_reuse_roles` for more information. What the sample setup enables ----------------------------- -The basic organizational structure described above enables a lot of different automation options. To reconfigure your entire infrastructure:: +The basic organizational structure described above enables a lot of different automation options. To reconfigure your entire infrastructure: + + .. code-block:: shell ansible-playbook -i production site.yml -To reconfigure NTP on everything:: +To reconfigure NTP on everything: + + .. code-block:: shell ansible-playbook -i production site.yml --tags ntp -To reconfigure only the webservers:: +To reconfigure only the webservers: + + .. code-block:: shell ansible-playbook -i production webservers.yml -To reconfigure only the webservers in Boston:: +To reconfigure only the webservers in Boston: + + .. code-block:: shell ansible-playbook -i production webservers.yml --limit boston -To reconfigure only the first 10 webservers in Boston, and then the next 10:: +To reconfigure only the first 10 webservers in Boston, and then the next 10: + + .. code-block:: shell ansible-playbook -i production webservers.yml --limit boston[0:9] ansible-playbook -i production webservers.yml --limit boston[10:19] -The sample setup also supports basic ad hoc commands:: +The sample setup also supports basic ad hoc commands: + + .. code-block:: shell ansible boston -i production -m ping ansible boston -i production -m command -a '/sbin/reboot' -To discover what tasks would run or what hostnames would be affected by a particular Ansible command:: +To discover what tasks would run or what hostnames would be affected by a particular Ansible command: + + .. code-block:: shell # confirm what task names would be run if I ran this command and said "just ntp tasks" ansible-playbook -i production webservers.yml --tags ntp --list-tasks