A fully-featured inventory file can serve as the source of truth for your network. Using an inventory file, a single playbook can maintain hundreds of network devices with a single command. This page shows you how to build an inventory file, step by step.

First, group your inventory logically. Best practice is to group servers and network devices by their What (application, stack or microservice), Where (datacenter or region), and When (development stage):

What: db, web, leaf, spine

Where: east, west, floor_19, building_A

When: dev, test, staging, prod

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.

Next, you can set values for many of the variables you needed in your first Ansible command in the inventory, so you can skip them in the ansible-playbook command. In this example, the inventory includes each network device’s IP, OS, and SSH user. If your network devices are only accessible by IP, you must add the IP to the inventory file. If you access your network devices using hostnames, the IP is not necessary.

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 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

The ansible-vault command provides encryption for files and/or individual variables like passwords. This tutorial will show you how to encrypt a single SSH password. You can use the commands below to encrypt other sensitive information, such as database passwords, privilege-escalation passwords and more.

First you must create a password for ansible-vault itself. It is used as the encryption key, and with this you can encrypt dozens of different passwords across your Ansible project. You can access all those secrets (encrypted values) with a single password (the ansible-vault password) when you run your playbooks. Here’s a simple example.

Create a file and write your password for ansible-vault to it:

echo"my-ansible-vault-pw" > ~/my-ansible-vault-pw-file

Create the encrypted ssh password for your VyOS network devices, pulling your ansible-vault password from the file you just created:

The --vault-id flag allows different vault passwords for different users or different levels of access. The output includes the user name my_user from your ansible-vault command and uses the YAML syntax key:value:

To see the original value, you can use the debug module. Please note if your YAML file defines the ansible_connection variable (as we used in our example), it will take effect when you execute the command below. To prevent this, please make a copy of the file without the ansible_connection variable.

Vault content can only be decrypted with the password that was used to encrypt it. If you want to stop using one password and move to a new one, you can update and re-encrypt existing vault content with ansible-vaultrekeymyfile, then provide the old password and the new password. Copies of vault content still encrypted with the old password can still be decrypted with old password.