From b023b89ec90ebb963058ea7d3fa682f850c12e8d Mon Sep 17 00:00:00 2001
From: Sandra McCann <samccann@redhat.com>
Date: Tue, 22 Jan 2019 11:49:51 -0500
Subject: [PATCH] add example of hosts in multiple inventory groups (#50895)

* add example of hosts in multiple groups

* fixed spacing

* added nested group example
---
 .../rst/user_guide/intro_inventory.rst        | 96 +++++++++++++++++--
 1 file changed, 90 insertions(+), 6 deletions(-)

diff --git a/docs/docsite/rst/user_guide/intro_inventory.rst b/docs/docsite/rst/user_guide/intro_inventory.rst
index b7c26af004d..39ef13544b0 100644
--- a/docs/docsite/rst/user_guide/intro_inventory.rst
+++ b/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.
 
@@ -110,7 +194,7 @@ In INI:
 
     [webservers]
     www[01:50].example.com
-    
+
 In YAML:
 
 .. code-block:: yaml
@@ -360,9 +444,9 @@ In this example, if both groups have the same priority, the result would normall
 Using multiple inventory sources
 ================================
 
-As an advanced use case you can target multiple inventory sources (directories, dynamic inventory scripts 
-or files supported by inventory plugins) at the same time by giving multiple inventory parameters from the command 
-line or by configuring :envvar:`ANSIBLE_INVENTORY`. This can be useful when you want to target normally 
+As an advanced use case you can target multiple inventory sources (directories, dynamic inventory scripts
+or files supported by inventory plugins) at the same time by giving multiple inventory parameters from the command
+line or by configuring :envvar:`ANSIBLE_INVENTORY`. This can be useful when you want to target normally
 separate environments, like staging and production, at the same time for a specific action.
 
 Target two sources from the command line like this::