* demonstrates best practices for group vars
* removes vm-specific var from example
* adds brackets to all [group:vars] refs
(cherry picked from commit 380c074808)
@ -17,7 +17,7 @@ First, group your inventory logically. Best practice is to group servers and net
Avoid spaces, hyphens, and preceding numbers (use ``floor_19``, not ``19th_floor``) in your group names. Group names are case sensitive.
This tiny example data center illustrates a basic group structure. You can group groups using the syntax ``metagroupname:children`` and listing groups as members of the metagroup. Here, the group ``network`` includes all leafs and all spines; the group ``datacenter`` includes all network devices plus all webservers.
This tiny example data center illustrates a basic group structure. You can group groups using the syntax ``[metagroupname:children]`` and listing groups as members of the metagroup. Here, the group ``network`` includes all leafs and all spines; the group ``datacenter`` includes all network devices plus all webservers.
..code-block:: yaml
@ -111,27 +111,17 @@ Variable Syntax
The syntax for variable values is different in inventory, in playbooks and in ``group_vars`` files, which are covered below. Even though playbook and ``group_vars`` files are both written in YAML, you use variables differently in each.
- In an inventory file you **must** use the syntax ``key=value`` for variable values: ``ansible_network_os=vyos``.
- In an ini-style inventory file you **must** use the syntax ``key=value`` for variable values: ``ansible_network_os=vyos``.
- In any file with the ``.yml`` or ``.yaml`` extension, including playbooks and ``group_vars`` files, you **must** use YAML syntax: ``key: value``
- In ``group_vars`` files, use the full ``key`` name: ``ansible_network_os: vyos``.
- In playbooks, use the short-form ``key`` name, which drops the ``ansible`` prefix: ``network_os: vyos``
As your inventory grows, you may want to group devices by platform and move shared variables out of the main inventory file into a set of group variable files. This reduces duplication further and sets the stage for managing devices on multiple platforms in a single inventory file. The directory tree for this setup looks like this:
..code-block:: console
.
├── first_playbook.yml
├── inventory
├── group_vars
└── vyos.yml
The group name must match the file name in your ``group_vars`` directory. In this example, Ansible will load the file ``group_vars/vyos.yml`` when it finds the group ``[vyos]`` in the inventory. So this inventory:
As your inventory grows, you may want to group devices by platform. This allows you to specify platform-specific variables easily for all devices on that platform:
..code-block:: yaml
@ -147,6 +137,11 @@ The group name must match the file name in your ``group_vars`` directory. In thi
vyos_leafs
vyos_spines
[vyos:vars]
ansible_connection=network_cli
ansible_network_os=vyos
ansible_user=my_vyos_user
[network:children]
vyos
@ -158,15 +153,6 @@ The group name must match the file name in your ``group_vars`` directory. In thi
vyos
servers
works with this ``group_vars/vyos.yml`` content:
..code-block:: yaml
ansible_connection: network_cli
ansible_network_os: vyos
ansible_user: my_vyos_user
With this setup, you can run first_playbook.yml with only two flags:
..code-block:: bash
@ -216,14 +202,15 @@ The :option:`--vault-id <ansible-playbook --vault-id>` flag allows different vau
An ``inventory`` file is an INI-like configuration file that defines the mapping of hosts into groups.
In our example, the inventory file defines the groups ``eos``, ``ios``, ``vyos`` and a "group of groups" called ``switches``. Further details about subgroups and inventory files can be found in the :ref:`Ansible inventory Group documentation <subgroups>`.
Because Ansible is a flexible tool, there are a number of ways to specify connection information and credentials. We recommend using the ``[my_group:vars]`` capability in your inventory file:
Connection & Credentials (group_vars)
-------------------------------------
Because Ansible is a flexible tool, there are a number of ways to specify connection information and credentials. We recommend using ``group_vars``.
..code-block:: ini
**group_vars/eos.yml**
[all:vars]
# these defaults can be overridden for any group in the [group:vars] section
.. FIXME FUTURE Gundalow - Link to network auth & proxy page (to be written)
..warning:: Never store passwords in plain text.
@ -139,14 +147,13 @@ Privilege escalation
Certain network platforms, such as eos and ios, have the concept of different privilege modes. Certain network modules, such as those that modify system state including users, will only work in high privilege states. Ansible version 2.5 added support for ``become`` when using ``connection: network_cli``. This allows privileges to be raised for the specific tasks that need them. Adding ``become: yes`` and ``become_method: enable`` informs Ansible to go into privilege mode before executing the task, as shown here:
**group_vars/eos.yml**
..code-block:: yaml
..code-block:: ini
ansible_connection: network_cli
ansible_network_os: eos
ansible_become: yes
ansible_become_method: enable
[eos:vars]
ansible_connection=network_cli
ansible_network_os=eos
ansible_become=yes
ansible_become_method=enable
For more information, see the :ref:`using become with network modules<become-network>` guide.
Alicia Cozine
7 years ago
committed by