add example of hosts in multiple inventory groups (#50895)

* add example of hosts in multiple groups

* fixed spacing

* added nested group example

docs/docsite/rst/user_guide/intro_inventory.rst

@@ -59,10 +59,94 @@ A YAML version would look like:
           two.example.com:
           three.example.com:
 
+.. _host_multiple_groups:
 
-It is ok to put systems in more than one group, for instance a server could be both a webserver and a dbserver.
-If you do, note that variables will come from all of the groups they are a member of. Variable precedence is detailed in a later chapter.
+Hosts in multiple groups
+------------------------
 
+You can put systems in more than one group, for instance a server could be both a webserver and in a specific datacenter.  For example, you could create groups that track:
+
+* What - An application, stack or microservice. (For example, database servers, web servers, etc).
+* Where - A datacenter or region, to talk to local DNS, storage, etc. (For example, east, west).
+* When - The development stage, to avoid testing on production resources. (For example, prod, test).
+
+Extending the previous YAML inventory to include what, when, and where would look like:
+
+.. code-block:: yaml
+
+  all:
+    hosts:
+      mail.example.com:
+    children:
+      webservers:
+        hosts:
+          foo.example.com:
+          bar.example.com:
+      dbservers:
+        hosts:
+          one.example.com:
+          two.example.com:
+          three.example.com:
+      east:
+        hosts:
+          foo.example.com:
+          one.example.com:
+          two.example.com:
+      west:
+        hosts:
+          bar.example.com:
+          three.example.com:
+      prod:
+        hosts:
+          foo.example.com:
+          one.example.com:
+          two.example.com:
+      test:
+        hosts:
+          bar.example.com:
+          three.example.com:
+
+You can see that ``one.example.com`` exists in the ``dbservers``, ``east``, and ``prod`` groups.
+
+You could also use nested groups to simplify ``prod`` and ``test`` in this inventory, for the same result:
+
+.. code-block:: yaml
+
+  all:
+    hosts:
+      mail.example.com:
+    children:
+      webservers:
+        hosts:
+          foo.example.com:
+          bar.example.com:
+      dbservers:
+        hosts:
+          one.example.com:
+          two.example.com:
+          three.example.com:
+      east:
+        hosts:
+          foo.example.com:
+          one.example.com:
+          two.example.com:
+      west:
+        hosts:
+          bar.example.com:
+          three.example.com:
+      prod:
+        children:
+          east:
+      test:
+        children:
+          west:
+
+
+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`.
+
+
+Hosts and non-standard ports
+-----------------------------
 If you have hosts that run on non-standard SSH ports you can put the port number after the hostname with a colon.
 Ports listed in your SSH config file won't be used with the `paramiko` connection but will be used with the `openssh` connection.