Repository: ansible/ansible
Pull request: Add examples for various inventory setups to the documentation
Fixes: #12480.


Problem statement:
Write sample inventory setups
##### ISSUE TYPE
Feature Idea

##### COMPONENT NAME
core

##### ANSIBLE VERSION
2.1

##### CONFIGURATION


##### OS / ENVIRONMENT


##### SUMMARY
Add a few examples of different inventory setups and classifications. Capture a few styles and business needs.
As example use a per environment inventory (dev,qa,prod) with groups for location (dc1, dc2) and function (lb, web, app, db). Another can be using divisions by BU/Client, etc.

##### STEPS TO REPRODUCE


##### EXPECTED RESULTS


##### ACTUAL RESULTS

Hints from issue discussion:
+1

Can we close this?
we can, but, i still think we should do it
Hi :) Would this be a good ticket for a first-time contributor? Right now it looks like I might have some time available in the next couple of months and would like to work on this 🙂
yes
Thanks :) Will do that then :)
@zerok thanks for offering to pick up this ticket - if you want support or help, join the #ansible-docs channel on freenode IRC!

Commit message: Add examples for various inventory setups to the documentation. This closes #12480.

Patch to review:
diff --git a/docs/docsite/rst/user_guide/intro_inventory.rst b/docs/docsite/rst/user_guide/intro_inventory.rst
index efa71055b862d8..4457ba7f529878 100644
--- a/docs/docsite/rst/user_guide/intro_inventory.rst
+++ b/docs/docsite/rst/user_guide/intro_inventory.rst
@@ -141,6 +141,7 @@ You could also use nested groups to simplify ``prod`` and ``test`` in this inven
         children:
           west:
 
+You can find more examples on how to organize your inventories and group your hosts in :ref:`inventory_setup_examples`.
 
 If you do have systems in multiple groups, note that variables will come from all of the groups they are a member of. Variable precedence is detailed in :ref:`ansible_variable_precedence`.
 
@@ -649,6 +650,92 @@ For a full list with available plugins and examples, see :ref:`connection_plugin
 .. note:: If you're reading the docs from the beginning, this may be the first example you've seen of an Ansible playbook. This is not an inventory file.
           Playbooks will be covered in great detail later in the docs.
 
+.. _inventory_setup_examples:
+
+Inventory setup examples
+========================
+
+.. _inventory_setup-per_environment:
+
+Example: One inventory per environment
+--------------------------------------
+
+If you need to manage multiple environments it's sometimes prudent to
+have only hosts of a single environment defined per inventory. This
+way, it is harder to, for instance, accidentally change the state of
+nodes inside the "test" environment when you actually wanted to update
+some "staging" servers.
+
+For the example mentioned above you could have an
+:file:`inventory_test` file::
+
+  [database-servers]
+  db01.test.example.com
+  db02.test.example.com
+
+  [app-servers]
+  app01.test.example.com
+  app02.test.example.com
+  app03.test.example.com
+
+In there are only host that are part of the "test"
+environment. "Staging" machines would be defined in another file
+called :file:`inventory_staging`::
+
+  [database-servers]
+  db01.staging.example.com
+  db02.staging.example.com
+
+  [app-servers]
+  app01.staging.example.com
+  app02.staging.example.com
+  app03.staging.example.com
+
+If you then have a playbook called :file:`site.yml`, then you'd apply
+that to all the app-servers in the test environment using the
+following command::
+
+  ansible-playbook -i inventory_test site.yml -l app-servers
+
+.. _inventory_setup-per_function:
+
+Example: Group by function
+--------------------------
+
+In the previous section you already saw an example for using groups in
+order to cluster hosts that have the same function. This allows you,
+for instance, to define firewall rules inside a playbook or role
+without affecting database servers::
+
+  - hosts: database-servers
+    tasks:
+    - name: allow access from 10.0.0.1
+      iptables:
+        chain: INPUT
+        jump: ACCEPT
+        source: 10.0.0.1
+
+.. _inventory_setup-per_location:
+
+Example: Group by location
+--------------------------
+
+Other tasks might be focused on where a certain host is located. Let's
+say that ``db01.test.example.com`` and ``app01.test.example.com`` are
+located in DC1 while ``db02.test.example.com`` is in DC2::
+
+  [dc1]
+  db01.test.example.com
+  app01.test.example.com
+
+  [dc2]
+  db02.test.example.com
+
+In practice, you might even end up mixing all these setups as you
+might need to, on one day, update all nodes in a specific data center
+while, on another day, update all the application servers no matter
+their location.
+
 .. seealso::
 
    :ref:`inventory_plugins`


Code review comments:
diff_hunk: @@ -649,6 +650,92 @@ For a full list with available plugins and examples, see :ref:`connection_plugin
 .. note:: If you're reading the docs from the beginning, this may be the first example you've seen of an Ansible playbook. This is not an inventory file.
           Playbooks will be covered in great detail later in the docs.
 
+.. _inventory_setup_examples:
+
+Inventory setup examples
+========================
+
+.. _inventory_setup-per_environment:
+
+Example: One inventory per environment
+--------------------------------------
+
+If you need to manage multiple environments it's sometimes prudent to
+have only hosts of a single environment defined per inventory. This
+way, it is harder to, for instance, accidentally change the state of
+nodes inside the "test" environment when you actually wanted to update
+some "staging" servers.
+
+For the example mentioned above you could have an
+:file:`inventory_test` file::
+
+  [database-servers]
path: docs/docsite/rst/user_guide/intro_inventory.rst
text: @user1:
avoid dashes, -servers seems redundant anyways

@author:
Fixed :) The "servers" postfix is consistent with other group-names in that document, though, so I opted to keep it.

diff_hunk: @@ -649,6 +650,92 @@ For a full list with available plugins and examples, see :ref:`connection_plugin
 .. note:: If you're reading the docs from the beginning, this may be the first example you've seen of an Ansible playbook. This is not an inventory file.
           Playbooks will be covered in great detail later in the docs.
 
+.. _inventory_setup_examples:
+
+Inventory setup examples
+========================
+
+.. _inventory_setup-per_environment:
+
+Example: One inventory per environment
+--------------------------------------
+
+If you need to manage multiple environments it's sometimes prudent to
+have only hosts of a single environment defined per inventory. This
+way, it is harder to, for instance, accidentally change the state of
+nodes inside the "test" environment when you actually wanted to update
+some "staging" servers.
+
+For the example mentioned above you could have an
+:file:`inventory_test` file::
+
+  [database-servers]
+  db01.test.example.com
+  db02.test.example.com
+
+  [app-servers]
+  app01.test.example.com
+  app02.test.example.com
+  app03.test.example.com
+
+In there are only host that are part of the "test"
path: docs/docsite/rst/user_guide/intro_inventory.rst
text: @user1:
```suggestion
That file only includes hosts that are part of the "test"
```

diff_hunk: @@ -649,6 +650,92 @@ For a full list with available plugins and examples, see :ref:`connection_plugin
 .. note:: If you're reading the docs from the beginning, this may be the first example you've seen of an Ansible playbook. This is not an inventory file.
           Playbooks will be covered in great detail later in the docs.
 
+.. _inventory_setup_examples:
+
+Inventory setup examples
+========================
+
+.. _inventory_setup-per_environment:
+
+Example: One inventory per environment
+--------------------------------------
+
+If you need to manage multiple environments it's sometimes prudent to
+have only hosts of a single environment defined per inventory. This
+way, it is harder to, for instance, accidentally change the state of
+nodes inside the "test" environment when you actually wanted to update
+some "staging" servers.
+
+For the example mentioned above you could have an
+:file:`inventory_test` file::
+
+  [database-servers]
+  db01.test.example.com
+  db02.test.example.com
+
+  [app-servers]
+  app01.test.example.com
+  app02.test.example.com
+  app03.test.example.com
+
+In there are only host that are part of the "test"
+environment. "Staging" machines would be defined in another file
+called :file:`inventory_staging`::
+
+  [database-servers]
+  db01.staging.example.com
+  db02.staging.example.com
+
+  [app-servers]
+  app01.staging.example.com
+  app02.staging.example.com
+  app03.staging.example.com
+
+If you then have a playbook called :file:`site.yml`, then you'd apply
path: docs/docsite/rst/user_guide/intro_inventory.rst
text: @user1:
```suggestion
To apply a playbook called :file:`site.yml`
```

diff_hunk: @@ -649,6 +650,92 @@ For a full list with available plugins and examples, see :ref:`connection_plugin
 .. note:: If you're reading the docs from the beginning, this may be the first example you've seen of an Ansible playbook. This is not an inventory file.
           Playbooks will be covered in great detail later in the docs.
 
+.. _inventory_setup_examples:
+
+Inventory setup examples
+========================
+
+.. _inventory_setup-per_environment:
+
+Example: One inventory per environment
+--------------------------------------
+
+If you need to manage multiple environments it's sometimes prudent to
+have only hosts of a single environment defined per inventory. This
+way, it is harder to, for instance, accidentally change the state of
+nodes inside the "test" environment when you actually wanted to update
+some "staging" servers.
+
+For the example mentioned above you could have an
+:file:`inventory_test` file::
+
+  [database-servers]
+  db01.test.example.com
+  db02.test.example.com
+
+  [app-servers]
+  app01.test.example.com
+  app02.test.example.com
+  app03.test.example.com
+
+In there are only host that are part of the "test"
+environment. "Staging" machines would be defined in another file
path: docs/docsite/rst/user_guide/intro_inventory.rst
text: @user1:
```suggestion
environment. Define the "staging" machines in another file
```

diff_hunk: @@ -649,6 +650,92 @@ For a full list with available plugins and examples, see :ref:`connection_plugin
 .. note:: If you're reading the docs from the beginning, this may be the first example you've seen of an Ansible playbook. This is not an inventory file.
           Playbooks will be covered in great detail later in the docs.
 
+.. _inventory_setup_examples:
+
+Inventory setup examples
+========================
+
+.. _inventory_setup-per_environment:
+
+Example: One inventory per environment
+--------------------------------------
+
+If you need to manage multiple environments it's sometimes prudent to
+have only hosts of a single environment defined per inventory. This
+way, it is harder to, for instance, accidentally change the state of
+nodes inside the "test" environment when you actually wanted to update
+some "staging" servers.
+
+For the example mentioned above you could have an
+:file:`inventory_test` file::
+
+  [database-servers]
+  db01.test.example.com
+  db02.test.example.com
+
+  [app-servers]
+  app01.test.example.com
+  app02.test.example.com
+  app03.test.example.com
+
+In there are only host that are part of the "test"
+environment. "Staging" machines would be defined in another file
+called :file:`inventory_staging`::
+
+  [database-servers]
+  db01.staging.example.com
+  db02.staging.example.com
+
+  [app-servers]
+  app01.staging.example.com
+  app02.staging.example.com
+  app03.staging.example.com
+
+If you then have a playbook called :file:`site.yml`, then you'd apply
+that to all the app-servers in the test environment using the
path: docs/docsite/rst/user_guide/intro_inventory.rst
text: @user1:
```suggestion
to all the app-servers in the test environment, use the
```