archive
/
ansible
mirror of https://github.com/ansible/ansible.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

revises inventory intro page (#49330)

Browse Source 
* revises inventory intro page

* changes :doc: to :ref: for links
pull/49331/head
Alicia Cozine 6 years ago committed by Sandra McCann
parent 3726d467ec
commit 02baae6e99
1 changed files with 28 additions and 31 deletions
Show Stats Download Patch File Download Diff File

59
docs/docsite/rst/user_guide/intro_inventory.rst
Unescape Escape View File

@ -1,11 +1,12 @@
.. _intro_inventory: .. _intro_inventory:
.. _inventory: .. _inventory:
**********************
Working with Inventory Working with Inventory
====================== **********************
.. contents:: Topics .. contents::
:local:
Ansible works against multiple systems in your infrastructure at the same time. Ansible works against multiple systems in your infrastructure at the same time.
It does this by selecting portions of systems listed in Ansible's inventory, It does this by selecting portions of systems listed in Ansible's inventory,
@ -18,8 +19,8 @@ Introduced in version 2.4, Ansible has inventory plugins to make this flexible a
.. _inventoryformat: .. _inventoryformat:
Hosts and Groups Inventory basics: hosts and groups
++++++++++++++++ ==================================
The inventory file can be in one of many formats, depending on the inventory plugins you have. The inventory file can be in one of many formats, depending on the inventory plugins you have.
For this example, the format for ``/etc/ansible/hosts`` is an INI-like (one of Ansible's defaults) and looks like this: For this example, the format for ``/etc/ansible/hosts`` is an INI-like (one of Ansible's defaults) and looks like this:
@ -129,8 +130,8 @@ As mentioned above, setting these in the inventory file is only a shorthand, and
.. _host_variables: .. _host_variables:
Host Variables Assigning a variable to one machine: host variables
++++++++++++++ ===================================================
As described above, it is easy to assign variables to hosts that will be used later in playbooks: As described above, it is easy to assign variables to hosts that will be used later in playbooks:
@ -154,8 +155,8 @@ The YAML version:
.. _group_variables: .. _group_variables:
Group Variables Assigning a variable to many machines: group variables
+++++++++++++++ ======================================================
Variables can also be applied to an entire group at once: Variables can also be applied to an entire group at once:
@ -187,11 +188,11 @@ Be aware that this is only a convenient way to apply variables to multiple hosts
.. _subgroups: .. _subgroups:
Groups of Groups, and Group Variables Inheriting variable values: group variables for groups of groups
+++++++++++++++++++++++++++++++++++++ ----------------------------------------------------------------
It is also possible to make groups of groups using the ``:children`` suffix in INI or the ``children:`` entry in YAML. You can make groups of groups using the ``:children`` suffix in INI or the ``children:`` entry in YAML.
You can apply variables using ``:vars`` or ``vars:``: You can apply variables to these groups of groups using ``:vars`` or ``vars:``:
.. code-block:: guess .. code-block:: guess
@ -256,7 +257,7 @@ Child groups have a couple of properties to note:
.. _default_groups: .. _default_groups:
Default groups Default groups
++++++++++++++ ==============
There are two default groups: ``all`` and ``ungrouped``. ``all`` contains every host. There are two default groups: ``all`` and ``ungrouped``. ``all`` contains every host.
``ungrouped`` contains all hosts that don't have another group aside from ``all``. ``ungrouped`` contains all hosts that don't have another group aside from ``all``.
@ -265,22 +266,18 @@ Though ``all`` and ``ungrouped`` are always present, they can be implicit and no
.. _splitting_out_vars: .. _splitting_out_vars:
Splitting Out Host and Group Specific Data Organizing host and group variables
++++++++++++++++++++++++++++++++++++++++++ ===================================
The preferred practice in Ansible is to not store variables in the main inventory file. Although you can store variables in the main inventory file, storing separate host and group variables files may help you track your variable values more easily.
In addition to storing variables directly in the inventory file, host and group variables can be stored in individual files relative to the inventory file (not directory, it is always the file). Host and group variables can be stored in individual files relative to the inventory file (not directory, it is always the file).
These variable files are in YAML format. Valid file extensions include '.yml', '.yaml', '.json', or no file extension. These variable files are in YAML format. Valid file extensions include '.yml', '.yaml', '.json', or no file extension.
See :ref:`yaml_syntax` if you are new to YAML. See :ref:`yaml_syntax` if you are new to YAML.
Assuming the inventory file path is:: Let's say, for example, that you keep your inventory file at ``/etc/ansible/hosts``. You have a host named 'foosball' that's a member of two groups: 'raleigh' and 'webservers'. That host will use variables
in YAML files at the following locations::
/etc/ansible/hosts
If the host is named 'foosball', and in groups 'raleigh' and 'webservers', variables
in YAML files at the following locations will be made available to the host::
/etc/ansible/group_vars/raleigh # can optionally end in '.yml', '.yaml', or '.json' /etc/ansible/group_vars/raleigh # can optionally end in '.yml', '.yaml', or '.json'
/etc/ansible/group_vars/webservers /etc/ansible/group_vars/webservers
@ -304,7 +301,7 @@ Ansible will read all the files in these directories in lexicographical order. A
All hosts that are in the 'raleigh' group will have the variables defined in these files All hosts that are in the 'raleigh' group will have the variables defined in these files
available to them. This can be very useful to keep your variables organized when a single available to them. This can be very useful to keep your variables organized when a single
file starts to be too big, or when you want to use :doc:`Ansible Vault<playbooks_vault>` on a part of a group's file starts to be too big, or when you want to use :ref:`Ansible Vault<playbooks_vault>` on a part of a group's
variables. variables.
Tip: The ``group_vars/`` and ``host_vars/`` directories can exist in Tip: The ``group_vars/`` and ``host_vars/`` directories can exist in
@ -320,8 +317,8 @@ is an excellent way to track changes to your inventory and host variables.
.. _how_we_merge: .. _how_we_merge:
How Variables Are Merged How variables are merged
++++++++++++++++++++++++ ========================
By default variables are merged/flattened to the specific host before a play is run. This keeps Ansible focused on the Host and Task, so groups don't really survive outside of inventory and host matching. By default, Ansible overwrites variables including the ones defined for a group and/or host (see :ref:`DEFAULT_HASH_BEHAVIOUR<DEFAULT_HASH_BEHAVIOUR>`). The order/precedence is (from lowest to highest): By default variables are merged/flattened to the specific host before a play is run. This keeps Ansible focused on the Host and Task, so groups don't really survive outside of inventory and host matching. By default, Ansible overwrites variables including the ones defined for a group and/or host (see :ref:`DEFAULT_HASH_BEHAVIOUR<DEFAULT_HASH_BEHAVIOUR>`). The order/precedence is (from lowest to highest):
@ -348,8 +345,8 @@ In this example, if both groups have the same priority, the result would normall
.. _behavioral_parameters: .. _behavioral_parameters:
List of Behavioral Inventory Parameters Connecting to hosts: behavioral inventory parameters
+++++++++++++++++++++++++++++++++++++++ ====================================================
As described above, setting the following variables control how Ansible interacts with remote hosts. As described above, setting the following variables control how Ansible interacts with remote hosts.
@ -392,7 +389,7 @@ ansible_ssh_executable (added in version 2.2)
This setting overrides the default behavior to use the system :command:`ssh`. This can override the ``ssh_executable`` setting in :file:`ansible.cfg`. This setting overrides the default behavior to use the system :command:`ssh`. This can override the ``ssh_executable`` setting in :file:`ansible.cfg`.
Privilege escalation (see :doc:`Ansible Privilege Escalation<become>` for further details): Privilege escalation (see :ref:`Ansible Privilege Escalation<become>` for further details):
ansible_become ansible_become
Equivalent to ``ansible_sudo`` or ``ansible_su``, allows to force privilege escalation Equivalent to ``ansible_sudo`` or ``ansible_su``, allows to force privilege escalation
@ -449,7 +446,7 @@ Examples from an Ansible-INI host file::
ruby_module_host ansible_ruby_interpreter=/usr/bin/ruby.1.9.3 ruby_module_host ansible_ruby_interpreter=/usr/bin/ruby.1.9.3
Non-SSH connection types Non-SSH connection types
++++++++++++++++++++++++ ------------------------
As stated in the previous section, Ansible executes playbooks over SSH but it is not limited to this connection type. As stated in the previous section, Ansible executes playbooks over SSH but it is not limited to this connection type.
With the host specific parameter ``ansible_connection=<connector>``, the connection type can be changed. With the host specific parameter ``ansible_connection=<connector>``, the connection type can be changed.

Write Preview
Loading…
Cancel
Save