Add examples for various inventory setups to the documentation (#62323)

* Add examples for various inventory setups to the documentation. This closes #12480.

* Update docs/docsite/rst/user_guide/intro_inventory.rst

Co-Authored-By: Sandra McCann <samccann@redhat.com>

* Update docs/docsite/rst/user_guide/intro_inventory.rst

Co-Authored-By: Sandra McCann <samccann@redhat.com>

* Update wording in inventory examples

Co-Authored-By: Sandra McCann <samccann@redhat.com>

* Update wording in inventory examples

Co-Authored-By: Sandra McCann <samccann@redhat.com>

* Use code-block and rename groups in inventory setup examples

* Fix group name in inventory setup example

Co-Authored-By: Sandra McCann <samccann@redhat.com>
This commit is contained in:
Horst Gutmann 2019-09-19 15:32:04 +02:00 committed by Sandra McCann
parent 95525030e2
commit 7047b66d34

View file

@ -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,100 @@ 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:
.. code-block:: ini
[dbservers]
db01.test.example.com
db02.test.example.com
[appservers]
app01.test.example.com
app02.test.example.com
app03.test.example.com
That file only includes hosts that are part of the "test"
environment. Define the "staging" machines in another file
called :file:`inventory_staging`:
.. code-block:: ini
[dbservers]
db01.staging.example.com
db02.staging.example.com
[appservers]
app01.staging.example.com
app02.staging.example.com
app03.staging.example.com
To apply a playbook called :file:`site.yml`
to all the app servers in the test environment, use the
following command::
ansible-playbook -i inventory_test site.yml -l appservers
.. _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:
.. code-block:: yaml
- hosts: dbservers
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:
.. code-block:: ini
[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`