mirror of
https://github.com/ansible/ansible-documentation.git
synced 2026-03-26 13:18:58 +07:00
inventory_guide/intro_inventory.rst: improve style. Assisted-by AI (#2834)
* inventory_guide/intro_inventory.rst: improve style. Assisted-by AI * Some manual human-in-the-loop fixes * Fix * Fix * Fix indentation
This commit is contained in:
Andrew Klychkov
@@ -5,22 +5,21 @@
|
||||
How to build your inventory
|
||||
***************************
|
||||
|
||||
Ansible automates tasks on managed nodes or "hosts" in your infrastructure, using a list or group of lists known as inventory. Ansible composes inventory from one or more 'inventory sources', one of these can be the list of host names you pass at the command line, but most Ansible users create inventory files. Your inventory defines the managed nodes you automate and the variables associated with those hosts. You can also specify groups, which allow for referencing multiple associated hosts to target for your automation or bulk defining of variables.
|
||||
Once your inventory is defined, you use :ref:`patterns <intro_patterns>` to select the hosts or groups you want Ansible to run against.
|
||||
Ansible automates tasks on managed nodes or "hosts" in your infrastructure by using a list or group of lists known as inventory. Ansible composes its inventory from one or more 'inventory sources'. While one of these sources can be the list of host names you pass at the command line, most Ansible users create inventory files. Your inventory defines the managed nodes you automate and the variables associated with those hosts. You can also specify groups. Groups allow you to reference multiple associated hosts to target for your automation or to define variables in bulk.
|
||||
Once you define your inventory, you use :ref:`patterns <intro_patterns>` to select the hosts or groups you want Ansible to run against.
|
||||
|
||||
The simplest inventory is a single file with a list of hosts and groups. The default location for this file is ``/etc/ansible/hosts``.
|
||||
You can specify a different inventory source(s) at the command line using the ``-i <path or expression>`` option(s) or in using the configuration system.
|
||||
The simplest inventory is a single file that contains a list of hosts and groups. The default location for this file is ``/etc/ansible/hosts``. You can specify a different inventory source or sources at the command line by using the ``-i <path or expression>`` option or by using the configuration system.
|
||||
|
||||
Ansible :ref:`inventory_plugins` supports a range of formats and sources to make your inventory flexible and customizable. As your inventory expands, you may need more than a single file to organize your hosts and groups. Here are three common options beyond the ``/etc/ansible/hosts`` file:
|
||||
Ansible :ref:`inventory_plugins` supports a range of formats and sources, which makes your inventory flexible and customizable. As your inventory expands, you might need more than a single file to organize your hosts and groups. You have the following common options beyond the ``/etc/ansible/hosts`` file:
|
||||
|
||||
- An inventory can be generated dynamically. For example, you can use an inventory plugin to list resources in one or more cloud providers (or other sources). See :ref:`intro_dynamic_inventory`.
|
||||
- You can generate an inventory dynamically. For example, you can use an inventory plugin to list resources in one or more cloud providers or other sources. See :ref:`intro_dynamic_inventory`.
|
||||
- You can use multiple sources for inventory, including both dynamic inventory and static files. See :ref:`using_multiple_inventory_sources`.
|
||||
- You can create a directory with multiple inventory sources, static or dynamic. See :ref:`inventory_directory`.
|
||||
|
||||
.. contents::
|
||||
:local:
|
||||
|
||||
.. note:: The following YAML snippets include an ellipsis to indicate they are part of a larger YAML file. You can find out more about YAML syntax at `YAML Basics <https://docs.ansible.com/ansible/latest/reference_appendices/YAMLSyntax.html#yaml-basics">`_.
|
||||
The following YAML snippets include an ellipsis (...) to indicate that the snippets are part of a larger YAML file. You can find out more about YAML syntax at `YAML Basics <https://docs.ansible.com/ansible/latest/reference_appendices/YAMLSyntax.html#yaml-basics">`_.
|
||||
|
||||
.. _inventoryformat:
|
||||
|
||||
@@ -28,8 +27,7 @@ Inventory basics: formats, hosts, and groups
|
||||
============================================
|
||||
|
||||
You can create your inventory file in one of many formats, depending on the inventory plugins you have.
|
||||
The most common formats are INI and YAML (as they are built-in), which is what we will mostly discuss in this introduction,
|
||||
but there are many more formats and sources that are possible.
|
||||
The most common formats are INI and YAML because Ansible includes built-in support for them. This introduction focuses on these two formats, but many other formats and sources are possible.
|
||||
|
||||
A basic INI ``/etc/ansible/hosts`` might look like this:
|
||||
|
||||
@@ -46,11 +44,11 @@ A basic INI ``/etc/ansible/hosts`` might look like this:
|
||||
two.example.com
|
||||
three.example.com
|
||||
|
||||
The headings in brackets are group names, which are used in classifying hosts
|
||||
and deciding what hosts you are controlling at what times and for what purpose.
|
||||
The headings in brackets are group names. You can use group names to classify hosts
|
||||
and to decide which hosts you are controlling at what times and for what purpose.
|
||||
Group names should follow the same guidelines as :ref:`valid_variable_names`.
|
||||
|
||||
Here's that same basic inventory file in YAML format:
|
||||
Here's the same basic inventory file in YAML format:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
@@ -72,21 +70,21 @@ Here's that same basic inventory file in YAML format:
|
||||
Default groups
|
||||
--------------
|
||||
|
||||
Even if you do not define any groups in your inventory file, Ansible creates two default groups: ``all`` and ``ungrouped`` after integrating all inventory sources. The ``all`` group contains every host. The ``ungrouped`` group contains all hosts that don't have another group aside from ``all``.
|
||||
Every host will always belong to at least 2 groups (``all`` and ``ungrouped`` or ``all`` and some other group). For example, in the basic inventory above, the host ``mail.example.com`` belongs to the ``all`` group and the ``ungrouped`` group; the host ``two.example.com`` belongs to the ``all`` group and the ``dbservers`` group. Though ``all`` and ``ungrouped`` are always present, they can be implicit and not appear in group listings like ``group_names``.
|
||||
Even if you do not define any groups in your inventory, Ansible creates two default groups: ``all`` and ``ungrouped``. The ``all`` group contains every host. The ``ungrouped`` group contains all hosts that do not belong to any other group.
|
||||
Every host always belongs to at least two groups (``all`` and ``ungrouped``, or ``all`` and another group). For example, in the basic inventory above, the host ``mail.example.com`` belongs to the ``all`` and ``ungrouped`` groups. The host ``two.example.com`` belongs to the ``all`` and ``dbservers`` groups. Although ``all`` and ``ungrouped`` are always present, they can be implicit and might not appear in group listings like ``group_names``.
|
||||
|
||||
.. _host_multiple_groups:
|
||||
|
||||
Hosts in multiple groups
|
||||
------------------------
|
||||
|
||||
You can put each host in more than one group. For example, a production web server in a data center in Atlanta might be included in groups called ``[prod]`` and ``[atlanta]`` and ``[webservers]``. You can create groups that track:
|
||||
You can put a host in more than one group. For example, you can include a production web server in a data center in Atlanta in the ``[prod]``, ``[atlanta]``, and ``[webservers]`` groups. You can create groups that track the following criteria:
|
||||
|
||||
* What - An application, stack or microservice (for example, database servers, web servers, and so on).
|
||||
* Where - A datacenter or region, to talk to local DNS, storage, and so on (for example, east, west).
|
||||
* When - The development stage, to avoid testing on production resources (for example, prod, test).
|
||||
* **What** - An application, stack, or microservice (for example, database servers, web servers, and so on).
|
||||
* **Where** - A datacenter or region, to talk to local DNS, storage, and so on (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 this:
|
||||
The following example extends the previous YAML inventory to include what, when, and where:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
@@ -121,21 +119,21 @@ Extending the previous YAML inventory to include what, when, and where would loo
|
||||
bar.example.com:
|
||||
three.example.com:
|
||||
|
||||
You can see that ``one.example.com`` exists in the ``dbservers``, ``east``, and ``prod`` groups.
|
||||
As the example shows, ``one.example.com`` exists in the ``dbservers``, ``east``, and ``prod`` groups.
|
||||
|
||||
.. _child_groups:
|
||||
|
||||
Grouping groups: parent/child group relationships
|
||||
-------------------------------------------------
|
||||
|
||||
You can create parent/child relationships among groups. Parent groups are also known as nested groups or groups of groups. For example, if all your production hosts are already in groups such as ``atlanta_prod`` and ``denver_prod``, you can create a ``production`` group that includes those smaller groups. This approach reduces maintenance because you can add or remove hosts from the parent group by editing the child groups.
|
||||
You can create parent/child relationships among groups. Parent groups are also known as nested groups or groups of groups. For example, if all your production hosts are already in groups such as ``atlanta_prod`` and ``denver_prod``, you can create a ``production`` group that includes those smaller groups. This approach reduces maintenance because you add or remove hosts from the parent group by editing the child groups.
|
||||
|
||||
To create parent/child relationships for groups:
|
||||
To create parent/child relationships for groups, use one of the following methods:
|
||||
|
||||
* in INI format, use the ``:children`` suffix
|
||||
* in YAML format, use the ``children:`` entry
|
||||
* In INI format, use the ``:children`` suffix.
|
||||
* In YAML format, use the ``children:`` entry.
|
||||
|
||||
Here is the same inventory as shown above, simplified with parent groups for the ``prod`` and ``test`` groups. The two inventory files give you the same results:
|
||||
The following example shows the same inventory as above, simplified with parent groups for the ``prod`` and ``test`` groups:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
@@ -167,18 +165,17 @@ Here is the same inventory as shown above, simplified with parent groups for the
|
||||
children:
|
||||
west:
|
||||
|
||||
Child groups have a couple of properties to note:
|
||||
Note the following properties of child groups:
|
||||
|
||||
* Any host that is a member of a child group is automatically a member of the parent group.
|
||||
* Groups can have multiple parents and children, but not circular relationships.
|
||||
* Hosts can also be in multiple groups, but there will only be **one** instance of a host at runtime. Ansible merges the data from multiple groups.
|
||||
* Hosts and groups are always 'global', if defined more than once under different 'branches' or 'instances' they are still the same host or group.
|
||||
Defining them more than once will just either add new information to them or overwrite any conflicting information with the latest given.
|
||||
* A group can have multiple parents and children, but not circular relationships.
|
||||
* A host can be in multiple groups, but Ansible processes only **one** instance of the host at runtime. Ansible merges the data from multiple groups.
|
||||
* Hosts and groups are always 'global'. If you define a host or group more than once under different 'branches' or 'instances', the host or group remains the same entity. Defining a host or group more than once either adds new information to it or overwrites any conflicting information with the latest definition.
|
||||
|
||||
Adding ranges of hosts
|
||||
----------------------
|
||||
|
||||
Some plugins, like YAML and INI, support adding ranges, if you have a lot of hosts with a similar pattern, you can add them as a range rather than listing each hostname separately:
|
||||
Some plugins, like YAML and INI, support adding ranges of hosts. If you have many hosts with a similar pattern, you can add the hosts as a range rather than listing each hostname separately:
|
||||
|
||||
In INI:
|
||||
|
||||
@@ -196,7 +193,7 @@ In YAML:
|
||||
hosts:
|
||||
www[01:50].example.com:
|
||||
|
||||
You can specify a stride (increments between sequence numbers) when defining a numeric range of hosts:
|
||||
You can specify a stride (increments between sequence numbers) when you define a numeric range of hosts:
|
||||
|
||||
In INI:
|
||||
|
||||
@@ -214,9 +211,9 @@ In YAML:
|
||||
hosts:
|
||||
www[01:50:2].example.com:
|
||||
|
||||
The example above would make the subdomains www01, www03, www05, ..., www49 match, but not www00, www02, www50 and so on, because the stride (increment) is 2 units each step.
|
||||
The example above matches the subdomains www01, www03, www05, ..., www49, but not www00, www02, www50, and so on, because the stride (increment) is 2 units for each step.
|
||||
|
||||
For numeric patterns, leading zeros can be included or removed, as desired. Ranges are inclusive. You can also define alphabetic ranges:
|
||||
For numeric patterns, you can include or remove leading zeros as desired. Ranges are inclusive. You can also define alphabetic ranges:
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
@@ -229,9 +226,9 @@ Passing multiple inventory sources
|
||||
==================================
|
||||
|
||||
You can target multiple inventory sources (static files, directories, dynamic inventory scripts
|
||||
or anything supported by inventory plugins) at the same time by specifying multiple inventory sources from the command
|
||||
line (see below) or by configuration, either setting :envvar:`ANSIBLE_INVENTORY` or in ansible.cfg (:ref:`DEFAULT_HOST_LIST`).
|
||||
his can be useful when you want to target normally separate environments, like staging and production, at the same time for a specific action.
|
||||
or anything supported by inventory plugins) at the same time. To do this, specify multiple inventory sources from the command
|
||||
line (see below) or by configuration, either by setting :envvar:`ANSIBLE_INVENTORY` or in ``ansible.cfg`` (:ref:`DEFAULT_HOST_LIST`).
|
||||
This capability can be useful when you want to target normally separate environments, like staging and production, at the same time for a specific action.
|
||||
|
||||
To target two inventory sources from the command line:
|
||||
|
||||
@@ -245,11 +242,11 @@ To target two inventory sources from the command line:
|
||||
Organizing inventory in a directory
|
||||
===================================
|
||||
|
||||
You can consolidate multiple inventory sources in a single directory. The simplest version of this is a directory with multiple files instead of a single inventory file. A single file gets difficult to maintain when it gets too long. If you have multiple teams and multiple automation projects, having one inventory file per team or project lets everyone easily find the hosts and groups that matter to them. You can also still use the files individually or in subsets, depending on how you configure or call Ansible.
|
||||
You can consolidate multiple inventory sources in a single directory. The simplest version of this approach is a directory with multiple files instead of a single inventory file. Maintaining a single file becomes difficult when the file gets too long. If you have multiple teams and multiple automation projects, creating one inventory file per team or project lets everyone easily find the hosts and groups that matter to them. You can also still use the files individually or in subsets, depending on how you configure or call Ansible.
|
||||
|
||||
These can use all formats or plugin configurations (YAML, ini, and so on). In this case, your directory is your 'single' inventory source but it aggregates the multiple sources it finds. There are some directories and extensions ignored by default, but you can change this in configuration (:ref:`INVENTORY_IGNORE_PATTERNS` and :ref:`INVENTORY_IGNORE_EXTS`).
|
||||
These files can use all formats or plugin configurations (for example, YAML or INI). In this case, your directory becomes your 'single' inventory source, and Ansible aggregates the multiple sources it finds in that directory. By default, Ansible ignores some directories and extensions, but you can change this behavior in the configuration (:ref:`INVENTORY_IGNORE_PATTERNS` and :ref:`INVENTORY_IGNORE_EXTS`).
|
||||
|
||||
You can also combine multiple inventory source types in an inventory directory. This can be useful for combining static and dynamic hosts and managing them as one inventory.
|
||||
You can also combine multiple inventory source types in an inventory directory. This method can be useful for combining static and dynamic hosts and managing them as one inventory.
|
||||
The following inventory directory combines an inventory plugin source, a dynamic inventory script,
|
||||
and a file with static hosts:
|
||||
|
||||
@@ -269,32 +266,32 @@ You can target this inventory directory as follows:
|
||||
|
||||
You can also configure the inventory directory in your ``ansible.cfg`` file. See :ref:`intro_configuration` for more details.
|
||||
|
||||
Files will be read and loaded in alphabetically sorted order from the top directory down.
|
||||
Ansible reads and loads files from the top directory down in alphabetically sorted order.
|
||||
|
||||
Managing inventory load order
|
||||
-----------------------------
|
||||
|
||||
Ansible loads inventory sources in the order supplied and will define hosts, groups and variables as it encounters them, adding the ``all`` and ``ungrouped`` at the end if needed.
|
||||
Ansible loads inventory sources in the order you supply them. It defines hosts, groups, and variables as it encounters them in the source files, adding the ``all`` and ``ungrouped`` groups at the end if needed.
|
||||
|
||||
Depending on the inventory plugin(s) used, you might need to consider rearranging the order to make sure parent/child-defined groups or hosts exist as the plugins involved expect or you might end up with a parsing error. For example, YAML and INI inventory will discard empty groups (no hosts associated) when they end processing each source.
|
||||
Depending on the inventory plugin or plugins you use, you might need to rearrange the order of sources to ensure that parent/child-defined groups or hosts exist as the plugins expect. Otherwise, you might encounter a parsing error. For example, the YAML and INI inventory plugins discard empty groups (groups with no associated hosts) when they finish processing each source.
|
||||
|
||||
Variables defined multiple times are overwritten, last one defined wins.
|
||||
If you define a variable multiple times, Ansible overwrites the previous value. The last definition wins.
|
||||
|
||||
.. _variables_in_inventory:
|
||||
|
||||
Adding variables to inventory
|
||||
=============================
|
||||
|
||||
You can define variables that relate to a specific host or group in inventory. A simple way to start is by adding variables directly to the hosts and groups in a YAML or INI inventory source.
|
||||
You can define variables that relate to a specific host or group in your inventory. A simple way to start is by adding variables directly to the hosts and groups in a YAML or INI inventory source.
|
||||
|
||||
We document adding variables in the inventory source for simplicity. However, you can also use :ref:`vars_plugins` to add variables from many other sources, Ansible, by default, ships with the :ref:`host_group_vars <host_group_vars_vars>` plugin, which allows defining variables in separate host and group variable files. This is a more robust approach to describing your system policy. Setting variables in the inventory source is only one way to do it. See :ref:`splitting_out_vars` for guidelines on storing variable values in individual files in the 'host_vars' and 'group_vars' directories.
|
||||
This guide documents how to add variables in the inventory source for simplicity. However, you can also use :ref:`vars_plugins` to add variables from many other sources. By default, Ansible ships with the :ref:`host_group_vars <host_group_vars_vars>` plugin, which allows you to define variables in separate host and group variable files. Using separate files is a more robust approach to describing your system policy than defining variables in the inventory source. See :ref:`splitting_out_vars` for guidelines on how to store variable values in individual files in the 'host_vars' and 'group_vars' directories.
|
||||
|
||||
.. _host_variables:
|
||||
|
||||
Assigning a variable to one machine: host variables
|
||||
===================================================
|
||||
|
||||
You can easily assign a variable to a single host and then use it later in playbooks. You can do this directly in your inventory file.
|
||||
You can easily assign a variable to a single host and then use that variable later in playbooks. You can do this directly in your inventory file.
|
||||
|
||||
In INI:
|
||||
|
||||
@@ -323,7 +320,7 @@ Unique values like non-standard SSH ports work well as host variables. You can a
|
||||
|
||||
badwolf.example.com:5309
|
||||
|
||||
This is a good way to define 'Connection variables' (variables used to configure ``connection``, ``shell``, ``become`` plugins to enable executing tasks on the host):
|
||||
You can use host variables to define 'Connection variables'. Connection variables configure ``connection``, ``shell``, and ``become`` plugins to enable task execution on the host. For example:
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
@@ -339,7 +336,7 @@ This is a good way to define 'Connection variables' (variables used to configure
|
||||
Inventory aliases
|
||||
-----------------
|
||||
|
||||
The ``inventory_hostname`` is the unique identifier for a host in Ansible, this can be an IP or a hostname, but also just an 'alias' or short name for the host.
|
||||
The ``inventory_hostname`` is the unique identifier for a host in Ansible. This identifier can be an IP address or a hostname, but it can also be just an 'alias' or short name for the host.
|
||||
|
||||
In INI:
|
||||
|
||||
@@ -357,9 +354,9 @@ In YAML:
|
||||
ansible_port: 5555
|
||||
ansible_host: 192.0.2.50
|
||||
|
||||
In this example, running Ansible against the host alias "jumper" will connect to 192.0.2.50 on port 5555. See :ref:`behavioral inventory parameters <behavioral_parameters>` to further customize the connection to hosts.
|
||||
In this example, running Ansible against the host alias "jumper" connects to 192.0.2.50 on port 5555. See :ref:`behavioral inventory parameters <behavioral_parameters>` to further customize the connection to hosts.
|
||||
|
||||
This is also useful to target the same host more than once, but remember that tasks can run in parallel:
|
||||
This feature is also useful for targeting the same host more than once, but remember that tasks can run in parallel:
|
||||
|
||||
In INI:
|
||||
|
||||
@@ -385,15 +382,15 @@ In YAML:
|
||||
Defining variables in INI format
|
||||
================================
|
||||
|
||||
Values passed in the INI format using the ``key=value`` syntax are interpreted differently depending on where they are declared:
|
||||
Ansible interprets values that you pass in the INI format by using the ``key=value`` syntax differently depending on where you declare them:
|
||||
|
||||
* When declared inline with the host, INI values are interpreted as Python literal structures (strings, numbers, tuples, lists, dicts, booleans, None). Host lines accept multiple ``key=value`` parameters per line. Therefore they need a way to indicate that a space is part of a value rather than a separator. Values that contain whitespace can be quoted (single or double). See the `Python shlex parsing rules`_ for details.
|
||||
* When you declare a value inline with the host, Ansible interprets the INI value as a Python literal structure (for example, a string, number, tuple, list, dict, boolean, or None). Host lines accept multiple ``key=value`` parameters per line. Therefore, you need a way to indicate that a space is part of a value rather than a separator. You can quote values that contain whitespace (using single or double quotes). See the `Python shlex parsing rules`_ for details.
|
||||
|
||||
* When declared in a ``:vars`` section, INI values are interpreted as strings. For example ``var=FALSE`` would create a string equal to 'FALSE'. Unlike host lines, ``:vars`` sections accept only a single entry per line, so everything after the ``=`` must be the value for the entry.
|
||||
* When you declare a value in a ``:vars`` section, Ansible interprets the INI value as a string. For example, ``var=FALSE`` creates a string with the value 'FALSE'. Unlike host lines, ``:vars`` sections accept only a single entry per line, so everything after the ``=`` becomes the value for the entry.
|
||||
|
||||
If a variable value set in an INI inventory must be a certain type (for example, a string or a boolean value), always specify the type with a filter in your task. Do not rely on types set in INI inventories when consuming variables.
|
||||
If you need a variable from an INI inventory to have a certain type (for example, a string or a boolean), always specify the type with a filter in your task. Do not rely on types that you set in INI inventories when you consume variables.
|
||||
|
||||
Consider using YAML format for inventory sources to avoid confusion on the actual type of a variable. The YAML inventory plugin processes variable values consistently and correctly.
|
||||
Consider using the YAML format for inventory sources to avoid confusion about the actual type of a variable. The YAML inventory plugin processes variable values consistently and correctly.
|
||||
|
||||
.. _Python shlex parsing rules: https://docs.python.org/3/library/shlex.html#parsing-rules
|
||||
|
||||
@@ -490,20 +487,20 @@ In YAML:
|
||||
northwest:
|
||||
southwest:
|
||||
|
||||
A child group's variables will have higher precedence (override) than a parent group's variables.
|
||||
A child group's variables have higher precedence (they override) than a parent group's variables.
|
||||
|
||||
.. _splitting_out_vars:
|
||||
|
||||
Organizing host and group variables
|
||||
===================================
|
||||
|
||||
Although you can define variables in the inventory source, you can also use :ref:`vars_plugins` to define alternate sources for variables.
|
||||
Although you can define variables in the inventory source, you can also use :ref:`vars_plugins` to define alternate sources for your variables.
|
||||
|
||||
For example, the default vars plugin shipped with Ansible (:ref:`host_group_vars <host_group_vars_vars>`) allows the use of separate host and group variables files, which may help you organize your variable values more easily. You can also use lists and hash data in host and group variables files, which you cannot do in your main inventory file.
|
||||
The default vars plugin that Ansible ships with, :ref:`host_group_vars <host_group_vars_vars>`, lets you use separate host and group variable files. This method helps you organize your variable values more easily. You can also use lists and hash data in these files, which you cannot do in your main inventory file.
|
||||
|
||||
For this plugin, host and group variable files must use YAML syntax. Valid file extensions include '.yml', '.yaml', '.json', or no file extension. See :ref:`yaml_syntax` if you are new to YAML.
|
||||
For the ``host_group_vars`` plugin, your host and group variable files must use YAML syntax. Valid file extensions are '.yml', '.yaml', '.json', or no file extension. See :ref:`yaml_syntax` if you are new to YAML.
|
||||
|
||||
The host_group_vars vars plugin loads host and group variable files by searching paths relative to the inventory source or the playbook file. If your inventory file at ``/etc/ansible/hosts`` contains a host named 'foosball' that belongs to two groups, 'raleigh' and 'webservers', that host will use variables in YAML files at the following locations:
|
||||
The ``host_group_vars`` plugin loads host and group variable files by searching paths relative to the inventory source or the playbook file. If your inventory file at ``/etc/ansible/hosts`` contains a host named 'foosball' that belongs to the 'raleigh' and 'webservers' groups, that host will use variables from the YAML files in the following locations:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
@@ -511,7 +508,7 @@ The host_group_vars vars plugin loads host and group variable files by searching
|
||||
/etc/ansible/group_vars/webservers
|
||||
/etc/ansible/host_vars/foosball
|
||||
|
||||
For example, if you group hosts in your inventory by datacenter, and each datacenter uses its own NTP server and database server, you can create a file called ``/etc/ansible/group_vars/raleigh`` to store the variables for the ``raleigh`` group:
|
||||
For example, if you group hosts in your inventory by datacenter, and each datacenter uses its own NTP server and database server, you can create a file named ``/etc/ansible/group_vars/raleigh`` to store the variables for the ``raleigh`` group:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
@@ -519,39 +516,41 @@ For example, if you group hosts in your inventory by datacenter, and each datace
|
||||
ntp_server: acme.example.org
|
||||
database_server: storage.example.org
|
||||
|
||||
You can also create *directories* named after your groups or hosts. Ansible will read all the files in these directories in lexicographical order. An example with the 'raleigh' group:
|
||||
You can also create *directories* named after your groups or hosts. Ansible reads all the files in these directories in lexicographical order. Here is an example with the 'raleigh' group:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
/etc/ansible/group_vars/raleigh/db_settings
|
||||
/etc/ansible/group_vars/raleigh/cluster_settings
|
||||
|
||||
All hosts 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
|
||||
file gets too big, or when you want to use :ref:`Ansible Vault<playbooks_vault>` on some group variables.
|
||||
All hosts in the 'raleigh' group have the variables that you define in these files
|
||||
available to them. This method is very useful for keeping your variables organized when a single
|
||||
file gets too big, or when you want to use :ref:`Ansible Vault <playbooks_vault>` on some group variables.
|
||||
|
||||
Ansible's :ref:`host_group_vars <host_group_vars_vars>` vars plugin can also add ``group_vars/`` and ``host_vars/`` directories to your playbook directory when using ``ansible-playbook``. But not all ansible commands have a playbook (for example, ``ansible``, ``ansible-console``, and so on), that is why the ``--playbook-dir`` option exists so you can provide the directory on the command line.
|
||||
If you have sources for the vars plugins relative to both the playbook directory and the inventory directory, variables sourced relative to the playbook will override variables sourced relative to the inventory source.
|
||||
Ansible's :ref:`host_group_vars <host_group_vars_vars>` vars plugin can also add ``group_vars/`` and ``host_vars/`` directories to your playbook directory when you use ``ansible-playbook``. However, not all Ansible commands have a playbook (for example, ``ansible`` or ``ansible-console``). For those commands, you can use the ``--playbook-dir`` option to provide the directory on the command line.
|
||||
If you have sources for the vars plugins relative to both the playbook directory and the inventory directory, the variables that Ansible sources relative to the playbook override the variables that it sources relative to the inventory source.
|
||||
|
||||
Keeping your inventory sources and relative variable directories and files in a Git repo (or other version control) is an excellent way to track changes to your inventory and variable definitions.
|
||||
To track changes to your inventory and variable definitions, keep your inventory sources and their relative variable directories and files in a Git repository or other version control system.
|
||||
|
||||
.. _how_we_merge:
|
||||
|
||||
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 do not 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 for inventory entities is (from lowest to highest):
|
||||
.. note:: Ansible merges variables from different sources and applies precedence to some variables over others according to a set of rules. For example, variables that occur higher in an inventory can override variables that occur lower in the inventory. See :ref:`ansible_variable_precedence` for more information.
|
||||
|
||||
- all group (because it is the 'parent' of all other groups)
|
||||
Before it runs a play, Ansible merges and flattens variables to the specific host. This process keeps Ansible focused on the Host and Task, so groups do not survive outside of inventory and host matching. By default, Ansible overwrites variables, including the ones that you define for a group or host (see :ref:`DEFAULT_HASH_BEHAVIOUR<DEFAULT_HASH_BEHAVIOUR>`). The order/precedence for inventory entities is (from lowest to highest):
|
||||
|
||||
The following list shows the order of precedence for inventory entities, from lowest to highest:
|
||||
|
||||
- ``all`` group (because it is the 'parent' of all other groups)
|
||||
- parent group
|
||||
- child group
|
||||
- host
|
||||
|
||||
By default, Ansible merges groups at the same parent/child level in alphabetical order, and variables from the last group loaded overwrite variables from the previous groups. For example, an ``a_group`` will be merged with ``b_group`` and ``b_group`` vars that match will overwrite the ones in ``a_group``.
|
||||
By default, Ansible merges groups at the same parent/child level in alphabetical order. Variables from the last group that Ansible loads overwrite variables from the previous groups. For example, Ansible merges an ``a_group`` with a ``b_group``, and matching variables from ``b_group`` overwrite the variables in ``a_group``.
|
||||
|
||||
.. note:: Ansible merges variables from different sources and applies precedence to some variables over others according to a set of rules. For example, variables that occur higher in an inventory can override variables that occur lower in the inventory. See :ref:`ansible_variable_precedence` for more information.
|
||||
|
||||
You can fine-tune this behavior by setting the group variable ``ansible_group_priority``, which overrides the alphabetical sorting for the merge order for groups of the same level (after the parent/child order is resolved). The larger the number, the later it will be merged, giving it higher priority. This variable defaults to ``1`` if not set. For example:
|
||||
You can fine-tune this merge behavior by setting the group variable ``ansible_group_priority``. This variable overrides the alphabetical sorting for the merge order for groups of the same level (after Ansible resolves the parent/child order). The larger the number, the later Ansible merges the group, giving it higher priority. This variable defaults to ``1`` if you do not set it. For example:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
@@ -563,22 +562,24 @@ You can fine-tune this behavior by setting the group variable ``ansible_group_pr
|
||||
vars:
|
||||
testvar: b
|
||||
|
||||
In this example, if both groups have the same priority, the result would normally have been ``testvar == b``, but since we are giving the ``a_group`` a higher priority the result will be ``testvar == a``.
|
||||
In this example, if both groups have the same priority, the result would normally be ``testvar == b``. However, because we give ``a_group`` a higher priority, the result is ``testvar == a``.
|
||||
|
||||
.. note:: ``ansible_group_priority`` can only be set in the inventory source and not in group_vars/, as the variable is used in the loading of group_vars.
|
||||
You can set ``ansible_group_priority`` only in an inventory source, not in ``group_vars/``. Ansible uses this variable when it loads the ``group_vars/`` directory.
|
||||
|
||||
Managing inventory variable load order
|
||||
--------------------------------------
|
||||
|
||||
When using multiple inventory sources, keep in mind that any variable conflicts are resolved according
|
||||
to the rules described in :ref:`how_we_merge` and :ref:`ansible_variable_precedence`. You can control the merging order of variables in inventory sources to get the variable value you need.
|
||||
This section describes how to control variable precedence by managing the load order of inventory sources. You can pass sources in a specific order at the command line or use prefixes in the filenames of sources within a directory.
|
||||
|
||||
When you pass multiple inventory sources at the command line, Ansible merges variables in the order you pass those parameters. If ``[all:vars]`` in staging inventory defines ``myvar = 1`` and production inventory defines ``myvar = 2``, then:
|
||||
When you use multiple inventory sources, remember that Ansible resolves any variable conflicts according to
|
||||
the rules described in :ref:`how_we_merge` and :ref:`ansible_variable_precedence`. You can control the merging order of variables in inventory sources to get the variable value you need.
|
||||
|
||||
* Pass ``-i staging -i production`` to run the playbook with ``myvar = 2``.
|
||||
* Pass ``-i production -i staging`` to run the playbook with ``myvar = 1``.
|
||||
When you pass multiple inventory sources at the command line, Ansible merges variables in the order you pass those parameters. If the ``[all:vars]`` section in the staging inventory defines ``myvar = 1`` and the production inventory defines ``myvar = 2``, then the following outcomes are true:
|
||||
|
||||
When you put multiple inventory sources in a directory, Ansible merges them in alphabetical order according to the file names. You can control the load order by adding prefixes to the files:
|
||||
* If you pass ``-i staging -i production``, Ansible runs the playbook with ``myvar = 2``.
|
||||
* If you pass ``-i production -i staging``, Ansible runs the playbook with ``myvar = 1``.
|
||||
|
||||
When you put multiple inventory sources in a directory, Ansible merges the sources in alphabetical order according to their filenames. You can control the load order by adding prefixes to the files:
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
@@ -590,7 +591,7 @@ When you put multiple inventory sources in a directory, Ansible merges them in a
|
||||
all.yml # assign variables to all hosts
|
||||
|
||||
If ``01-openstack.yml`` defines ``myvar = 1`` for the group ``all``, ``02-dynamic-inventory.py`` defines ``myvar = 2``,
|
||||
and ``03-static-inventory`` defines ``myvar = 3``, the playbook will be run with ``myvar = 3``.
|
||||
and ``03-static-inventory`` defines ``myvar = 3``, Ansible runs the playbook with ``myvar = 3``.
|
||||
|
||||
For more details on inventory plugins and dynamic inventory scripts see :ref:`inventory_plugins` and :ref:`intro_dynamic_inventory`.
|
||||
|
||||
@@ -599,93 +600,93 @@ For more details on inventory plugins and dynamic inventory scripts see :ref:`in
|
||||
Connecting to hosts: behavioral inventory parameters
|
||||
====================================================
|
||||
|
||||
As described above, setting the following variables controls how Ansible interacts with remote hosts.
|
||||
As described above, you can set the following variables to control how Ansible interacts with remote hosts.
|
||||
|
||||
Host connection:
|
||||
|
||||
.. include:: shared_snippets/SSH_password_prompt.txt
|
||||
|
||||
ansible_connection
|
||||
Connection type to the host. This can be the name of any Ansible connection plugin. SSH protocol types are ``ssh`` or ``paramiko``. The default is ``ssh``.
|
||||
Specifies the connection type to the host. This can be the name of any Ansible connection plugin. SSH protocol types are ``ssh`` or ``paramiko``. The default is ``ssh``.
|
||||
|
||||
General for all connections:
|
||||
|
||||
ansible_host
|
||||
A resolvable name or IP of the host to connect to, if different from the alias you wish to give to it. Never set it to depend on ``inventory_hostname``, if you really need something like that use ``inventory_hostname_short``, so it can work with delegation.
|
||||
Specifies the resolvable name or IP of the host to connect to, if it is different from the alias you wish to give to it. Never set it to depend on ``inventory_hostname``. If you really need something like that, use ``inventory_hostname_short`` so it can work with delegation.
|
||||
ansible_port
|
||||
The connection port number, if not the default (22 for ssh)
|
||||
The connection port number, if not the default (22 for ssh).
|
||||
ansible_user
|
||||
The username to use when connecting (logging in) to the host
|
||||
The username to use when connecting (logging in) to the host.
|
||||
ansible_password
|
||||
The password to use to authenticate to the host (never store this variable in plain text; always use a vault. See :ref:`tip_for_variables_and_vaults`)
|
||||
The password to use to authenticate to the host. (Never store this variable in plain text. Always use a vault. See :ref:`tip_for_variables_and_vaults`.)
|
||||
|
||||
|
||||
Specific to the SSH connection plugin:
|
||||
|
||||
ansible_ssh_private_key_file
|
||||
Private key file used by SSH. Useful if using multiple keys and you do not want to use SSH agent.
|
||||
Private key file used by SSH. This is useful if you use multiple keys and you do not want to use SSH agent.
|
||||
ansible_ssh_common_args
|
||||
This setting is always appended to the default command line for :command:`sftp`, :command:`scp`,
|
||||
and :command:`ssh`. Useful to configure a ``ProxyCommand`` for a certain host (or
|
||||
group).
|
||||
Ansible always appends this setting to the default command line for :command:`sftp`, :command:`scp`,
|
||||
and :command:`ssh`. This is useful for configuring a ``ProxyCommand`` for a certain host or
|
||||
group.
|
||||
ansible_sftp_extra_args
|
||||
This setting is always appended to the default :command:`sftp` command line.
|
||||
Ansible always appends this setting to the default :command:`sftp` command line.
|
||||
ansible_scp_extra_args
|
||||
This setting is always appended to the default :command:`scp` command line.
|
||||
Ansible always appends this setting to the default :command:`scp` command line.
|
||||
ansible_ssh_extra_args
|
||||
This setting is always appended to the default :command:`ssh` command line.
|
||||
Ansible always appends this setting to the default :command:`ssh` command line.
|
||||
ansible_ssh_pipelining
|
||||
Determines whether or not to use SSH pipelining. This can override the ``pipelining`` setting in :file:`ansible.cfg`.
|
||||
Specifies whether to use SSH pipelining. This can override the ``pipelining`` setting in :file:`ansible.cfg`.
|
||||
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` under ``ssh_connection``.
|
||||
This setting overrides the default behavior to use the system :command:`ssh`. It can override the ``ssh_executable`` setting in the ``ssh_connection`` section of :file:`ansible.cfg`.
|
||||
|
||||
|
||||
Privilege escalation (see :ref:`Ansible Privilege Escalation<become>` for further details):
|
||||
|
||||
ansible_become
|
||||
Equivalent to ``ansible_sudo`` or ``ansible_su``, allows to force privilege escalation
|
||||
Equivalent to ``ansible_sudo`` or ``ansible_su``; allows you to force privilege escalation.
|
||||
ansible_become_method
|
||||
Allows to set privilege escalation method to a matching become plugin
|
||||
Allows you to set the privilege escalation method to a matching become plugin.
|
||||
ansible_become_user
|
||||
Equivalent to ``ansible_sudo_user`` or ``ansible_su_user``, allows you to set the user you become through privilege escalation
|
||||
Equivalent to ``ansible_sudo_user`` or ``ansible_su_user``; allows you to set the user you become through privilege escalation.
|
||||
ansible_become_password
|
||||
Equivalent to ``ansible_sudo_password`` or ``ansible_su_password``, allows you to set the privilege escalation password (never store this variable in plain text; always use a vault. See :ref:`tip_for_variables_and_vaults`)
|
||||
Equivalent to ``ansible_sudo_password`` or ``ansible_su_password``; allows you to set the privilege escalation password. (Never store this variable in plain text. Always use a vault. See :ref:`tip_for_variables_and_vaults`.)
|
||||
ansible_become_exe
|
||||
Equivalent to ``ansible_sudo_exe`` or ``ansible_su_exe``, allows you to set the executable for the escalation method selected
|
||||
Equivalent to ``ansible_sudo_exe`` or ``ansible_su_exe``; allows you to set the executable for the escalation method you selected.
|
||||
ansible_become_flags
|
||||
Equivalent to ``ansible_sudo_flags`` or ``ansible_su_flags``, allows you to set the flags passed to the selected escalation method. This can be also set globally in :file:`ansible.cfg` in the ``become_flags`` option under ``privilege_escalation``.
|
||||
Equivalent to ``ansible_sudo_flags`` or ``ansible_su_flags``; allows you to set the flags passed to the selected escalation method. You can also set this globally in :file:`ansible.cfg` in the ``become_flags`` option under ``privilege_escalation``.
|
||||
|
||||
Remote host environment parameters:
|
||||
|
||||
.. _ansible_shell_type:
|
||||
|
||||
ansible_shell_type
|
||||
The shell type of the target system. You should not use this setting unless you have set the
|
||||
:ref:`ansible_shell_executable<ansible_shell_executable>` to a non-Bourne (sh) compatible shell. By default, commands are
|
||||
formatted using ``sh``-style syntax. Setting this to ``csh`` or ``fish`` will cause commands
|
||||
executed on target systems to follow those shell's syntax instead.
|
||||
Specifies the shell type of the target system. You should not use this setting unless you have set the
|
||||
:ref:`ansible_shell_executable<ansible_shell_executable>` to a non-Bourne (sh) compatible shell. By default, Ansible
|
||||
formats commands using ``sh``-style syntax. If you set this to ``csh`` or ``fish``, commands
|
||||
that Ansible executes on target systems follow those shell's syntax instead.
|
||||
|
||||
.. _ansible_python_interpreter:
|
||||
|
||||
ansible_python_interpreter
|
||||
The target host Python path. This is useful for systems with more
|
||||
than one Python or not located at :command:`/usr/bin/python` such as \*BSD, or where :command:`/usr/bin/python`
|
||||
is not a 2.X series Python. We do not use the :command:`/usr/bin/env` mechanism as that requires the remote user's
|
||||
path to be set right and also assumes the :program:`python` executable is named python, where the executable might
|
||||
Specifies the target host Python path. This is useful for systems with more
|
||||
than one Python or for systems where Python is not located at :command:`/usr/bin/python`, such as \*BSD, or where :command:`/usr/bin/python`
|
||||
is not a 2.X series Python. We do not use the :command:`/usr/bin/env` mechanism because that requires the remote user's
|
||||
path to be set correctly and also assumes the :program:`python` executable is named python, where the executable might
|
||||
be named something like :program:`python2.6`.
|
||||
|
||||
ansible_*_interpreter
|
||||
Works for anything such as ruby or perl and works just like :ref:`ansible_python_interpreter<ansible_python_interpreter>`.
|
||||
This replaces shebang of modules that will run on that host.
|
||||
Works for any language, such as Ruby or Perl, and works just like :ref:`ansible_python_interpreter<ansible_python_interpreter>`.
|
||||
This variable replaces the shebang of modules that will run on that host.
|
||||
|
||||
.. versionadded:: 2.1
|
||||
|
||||
.. _ansible_shell_executable:
|
||||
|
||||
ansible_shell_executable
|
||||
This sets the shell the ansible control node will use on the target machine,
|
||||
overrides ``executable`` in :file:`ansible.cfg` which defaults to
|
||||
:command:`/bin/sh`. You should only change this value if it is not possible
|
||||
This setting sets the shell the Ansible control node will use on the target machine.
|
||||
It overrides ``executable`` in :file:`ansible.cfg`, which defaults to
|
||||
:command:`/bin/sh`. You should only change this value if it is not possible
|
||||
to use :command:`/bin/sh` (in other words, if :command:`/bin/sh` is not installed on the target
|
||||
machine or cannot be run from sudo.).
|
||||
|
||||
@@ -701,9 +702,9 @@ Examples from an Ansible-INI host file:
|
||||
Non-SSH connection types
|
||||
------------------------
|
||||
|
||||
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=<connection plugin name>``, the connection type can be changed.
|
||||
For a full list with available plugins and examples, see :ref:`connection_plugin_list`.
|
||||
As stated in the previous section, Ansible executes playbooks over SSH by default, but it is not limited to this connection type.
|
||||
You can change the connection type with the host-specific parameter ``ansible_connection=<connection plugin name>``.
|
||||
For a full list of available plugins and examples, see :ref:`connection_plugin_list`.
|
||||
|
||||
.. _inventory_setup_examples:
|
||||
|
||||
@@ -717,13 +718,13 @@ See also :ref:`sample_setup`, which shows inventory along with playbooks and oth
|
||||
Example: One inventory per environment
|
||||
--------------------------------------
|
||||
|
||||
If you need to manage multiple environments it is sometimes prudent to
|
||||
have only hosts of a single environment defined per inventory. This
|
||||
If you need to manage multiple environments, consider defining only the
|
||||
hosts of a single environment in each inventory. This
|
||||
way, it is harder to, for example, accidentally change the state of
|
||||
nodes inside the "test" environment when you wanted to update
|
||||
some "staging" servers.
|
||||
|
||||
For the example mentioned above you could have an
|
||||
For the example mentioned above, you could have an
|
||||
:file:`inventory_test` file:
|
||||
|
||||
.. code-block:: ini
|
||||
@@ -738,7 +739,7 @@ For the example mentioned above you could have an
|
||||
app03.test.example.com
|
||||
|
||||
That file only includes hosts that are part of the "test"
|
||||
environment. Define the "staging" machines in another file
|
||||
environment. You can define the "staging" machines in another file
|
||||
called :file:`inventory_staging`:
|
||||
|
||||
.. code-block:: ini
|
||||
@@ -765,10 +766,10 @@ following command:
|
||||
Example: Group by function
|
||||
--------------------------
|
||||
|
||||
In the previous section, you already saw an example of using groups in
|
||||
order to cluster hosts that have the same function. This allows you,
|
||||
In the previous section, you already saw an example of using groups to
|
||||
cluster hosts that have the same function. This approach allows you,
|
||||
for example, to define firewall rules inside a playbook or role
|
||||
affecting only database servers:
|
||||
that affect only database servers:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
@@ -785,9 +786,9 @@ affecting only database servers:
|
||||
Example: Group by location
|
||||
--------------------------
|
||||
|
||||
Other tasks might be focused on where a certain host is located. Let's
|
||||
Other tasks might focus 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:
|
||||
located in DC1, while ``db02.test.example.com`` is in DC2:
|
||||
|
||||
.. code-block:: ini
|
||||
|
||||
@@ -798,9 +799,9 @@ located in DC1 while ``db02.test.example.com`` is in DC2:
|
||||
[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
|
||||
In practice, you might end up mixing all these setups. For example, you
|
||||
might need to update all nodes in a specific data center
|
||||
on one day, while on another day, you might need to update all the application servers no matter
|
||||
their location.
|
||||
|
||||
.. seealso::
|
||||
|
||||
Reference in New Issue
Block a user