wbrawner/ansible
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

demonstrates best practices for group vars (#37930) (#38287)

Browse source 
* demonstrates best practices for group vars

* removes vm-specific var from example

* adds brackets to all [group:vars] refs

(cherry picked from commit 380c074808)
This commit is contained in:
Alicia Cozine 2018-04-05 07:17:44 -05:00 committed by John R Barker
parent 05cf76cbd7
commit 92562a2ba9
2 changed files with 62 additions and 68 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

43
docs/docsite/rst/network/getting_started/first_inventory.rst
View file

@ -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``
Move Group Variables to ``group_vars`` Files
Group Inventory by Platform
================================================================================
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
65656439626166666363323435613131643066353762333232326232323565376635
Encryption successful
Copy this output into your ``group_vars/vyos.yml`` file, which now looks like this:
Copy this output into your inventory file under ``[vyos:vars]``, which now looks like this:
.. code-block:: yaml
ansible_connection: network_cli
ansible_network_os: vyos
ansible_user: my_vyos_user
ansible_ssh_pass: !vault |
[vyos:vars]
ansible_connection=network_cli
ansible_network_os=vyos
ansible_user=my_vyos_user
ansible_ssh_pass= !vault |
$ANSIBLE_VAULT;1.2;AES256;my_user
66386134653765386232383236303063623663343437643766386435663632343266393064373933
3661666132363339303639353538316662616638356631650a316338316663666439383138353032

87
docs/docsite/rst/network/user_guide/network_best_practices_2.5.rst
View file

@ -45,67 +45,76 @@ The examples on this page use the following structure:
.
├── facts-demo.yml
├── group_vars
│   ├── eos.yml
│   └── ios.yml
└── inventory
Inventory
---------
Inventory, Connections, Credentials: Grouping Devices and Variables
-------------------------------------------------------------------
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)
-------------------------------------
.. code-block:: ini
Because Ansible is a flexible tool, there are a number of ways to specify connection information and credentials. We recommend using ``group_vars``.
[all:vars]
# these defaults can be overridden for any group in the [group:vars] section
ansible_connection=network_cli
ansible_user=ansible
**group_vars/eos.yml**
[switches:children]
eos
ios
vyos
.. code-block:: yaml
[eos]
veos01 ansible_host=veos-01.example.net
veos02 ansible_host=veos-02.example.net
veos03 ansible_host=veos-03.example.net
veos04 ansible_host=veos-04.example.net
ansible_connection: network_cli
ansible_network_os: eos
ansible_user: myuser
ansible_ssh_pass: !vault |
[eos:vars]
ansible_become=yes
ansible_become_method=enable
ansible_network_os=eos
ansible_user=my_eos_user
ansible_ssh_pass= !vault |
$ANSIBLE_VAULT;1.1;AES256
37373735393636643261383066383235363664386633386432343236663533343730353361653735
6131363539383931353931653533356337353539373165320a316465383138636532343463633236
37623064393838353962386262643230303438323065356133373930646331623731656163623333
3431353332343530650a373038366364316135383063356531633066343434623631303166626532
9562
ansible_become: yes
ansible_become_method: enable
**group_vars/ios.yml**
[ios]
ios01 ansible_host=ios-01.example.net
ios02 ansible_host=ios-02.example.net
ios03 ansible_host=ios-03.example.net
.. code-block:: yaml
ansible_connection: network_cli
ansible_network_os: ios
ansible_user: myiosuser
ansible_ssh_pass: !vault |
[ios:vars]
ansible_become=yes
ansible_become_method=enable
ansible_network_os=ios
ansible_user=my_ios_user
ansible_ssh_pass= !vault |
$ANSIBLE_VAULT;1.1;AES256
34623431313336343132373235313066376238386138316466636437653938623965383732373130
3466363834613161386538393463663861636437653866620a373136356366623765373530633735
34323262363835346637346261653137626539343534643962376139366330626135393365353739
3431373064656165320a333834613461613338626161633733343566666630366133623265303563
8472
ansible_become: yes
ansible_become_method: enable
**group_vars/vyos.yml**
[vyos]
vyos01 ansible_host=vyos-01.example.net
vyos02 ansible_host=vyos-02.example.net
vyos03 ansible_host=vyos-03.example.net
.. code-block:: yaml
ansible_connection: network_cli
ansible_network_os: vyos
ansible_user: myvyosuser
ansible_ssh_pass: !vault |
[vyos:vars]
ansible_network_os=vyos
ansible_user=my_vyos_user
ansible_ssh_pass= !vault |
$ANSIBLE_VAULT;1.1;AES256
39336231636137663964343966653162353431333566633762393034646462353062633264303765
6331643066663534383564343537343334633031656538370a333737656236393835383863306466
@ -113,7 +122,6 @@ Because Ansible is a flexible tool, there are a number of ways to specify connec
3665626431626532630a353564323566316162613432373738333064366130303637616239396438
9853
.. 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:: ini
.. code-block:: yaml
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.