Building an inventory

Inventories organize managed nodes in centralized files that provide Ansible with system information and network locations. Using an inventory file, Ansible can manage a large number of hosts with a single command. Inventories also help you use Ansible more efficiently by reducing the number of command-line options you need to specify. For example, inventories usually contain the SSH user so you do not need to include the -u flag when running Ansible commands.

In the previous section, you added managed nodes directly to the /etc/ansible/hosts file. Now let’s create an inventory file that you can add to source control for flexibility, reuse, and for sharing with other users.

Note

Inventory files can be in INI or YAML format. For demonstration purposes, this section uses YAML format only.

Complete the following steps:

  1. Open a terminal window on your control node.

  2. Create a new inventory file named inventory.yaml in any directory and open it for editing.

  3. Add a new group for your hosts then specify the IP address or fully qualified domain name (FQDN) of each managed node with the ansible_host field. The following example adds the IP addresses of three virtual machines in KVM:

    virtualmachines:
      hosts:
        vm01:
          ansible_host: 192.0.2.50
        vm02:
          ansible_host: 192.0.2.51
        vm03:
          ansible_host: 192.0.2.52
    
  4. Verify your inventory. If you created your inventory in a directory other than your home directory, specify the full path with the -i option.

    ansible-inventory -i inventory.yaml --list
    
  5. Ping the managed nodes in your inventory. In this example, the group name is virtualmachines which you can specify with the ansible command instead of all.

    ansible virtualmachines -m ping -i inventory.yaml
    
    vm03 | SUCCESS => {
        "ansible_facts": {
            "discovered_interpreter_python": "/usr/bin/python3"
        },
        "changed": false,
        "ping": "pong"
    }
    vm02 | SUCCESS => {
        "ansible_facts": {
            "discovered_interpreter_python": "/usr/bin/python3"
        },
        "changed": false,
        "ping": "pong"
    }
    vm01 | SUCCESS => {
        "ansible_facts": {
            "discovered_interpreter_python": "/usr/bin/python3"
        },
        "changed": false,
        "ping": "pong"
    }
    

Congratulations! You have successfully built an inventory.

Tips for building inventories

  • Ensure that group names are meaningful and unique. Group names are also case sensitive.

  • Avoid spaces, hyphens, and preceding numbers (use floor_19, not 19th_floor) in group names.

  • Group hosts in your inventory logically according to their What, Where, and When.

    What

    Group hosts according to the topology, for example: db, web, leaf, spine.

    Where

    Group hosts by geographic location, for example: datacenter, region, floor, building.

    When

    Group hosts by stage, for example: development, test, staging, production.

Use metagroups

Create a metagroup that organizes multiple groups in your inventory with the following syntax:

metagroupname:
  children:

The following inventory illustrates a basic structure for a data center. This example inventory contains a network metagroup that includes all network devices and a datacenter metagroup that includes the network group and all webservers.

leafs:
  hosts:
    leaf01:
      ansible_host: 192.0.2.100
    leaf02:
      ansible_host: 192.0.2.110

spines:
  hosts:
    spine01:
      ansible_host: 192.0.2.120
    spine02:
      ansible_host: 192.0.2.130

network:
  children:
    leafs:
    spines:

webservers:
  hosts:
    webserver01:
      ansible_host: 192.0.2.140
    webserver02:
      ansible_host: 192.0.2.150

datacenter:
  children:
    network:
    webservers:

Create variables

Variables set values for managed nodes, such as the IP address, FQDN, operating system, and SSH user, so you do not need to pass them when running Ansible commands.

Variables can apply to specific hosts.

webservers:
  hosts:
    webserver01:
      ansible_host: 192.0.2.140
      http_port: 80
    webserver02:
      ansible_host: 192.0.2.150
      http_port: 443

Variables can also apply to all hosts in a group.

webservers:
  hosts:
    webserver01:
      ansible_host: 192.0.2.140
      http_port: 80
    webserver02:
      ansible_host: 192.0.2.150
      http_port: 443
  vars:
    ansible_user: my_server_user

Now that you know how to build an inventory, continue by learning how to create a playbook.

See also

How to build your inventory

Learn more about inventories in YAML or INI format.

Adding variables to inventory

Find out more about inventory variables and their syntax.

Ansible Vault

Find out how to encrypt sensitive content in your inventory such as passwords and keys.