inventory overview

It is a file (pseudo ini or yaml) that define hosts that Ansible may target.

Main declaration rules 
– Hosts may be specified in a group or not.
– A even host may be specified in multiple groups.
– A group may have children groups.
– A host may specify a range (numeric or alphabetic) to spare quite similar host declarations.

Inventory file location 
Default file for inventory : /etc/ansible/hosts.
We could specify a different inventory file at the command line using the -i INVENTORY_PATH flag.

Inventory ini example that illustrates main rules

#these are ungrouped hosts
monitoring1.foo.com
#the range pattern allows to declare 5 hosts here
backup[01:05].foo.com
 
#group database
[database]
database1.us.foo.com
database2.eur.foo.com
database3.asia.foo.com
 
#group application
[application]
application1.us.foo.com
application2.eur.foo.com
application3.asia.foo.com
 
#hosts can be declared in multiple groups
#group us
[us]
database1.us.foo.com
application1.us.foo.com
 
#group eur
[eur]
database2.eur.foo.com
application2.eur.foo.com
 
#group asia
[asia]
database3.asia.foo.com
application3.asia.foo.com
 
#a group can have children groups
#group business
[business:children]
database
application

We may notice that all and ungrouped groups don’t appear while these exist.

Here the yml version (written at the hand)

all:
  children:
    asia:
      hosts:
        application3.asia.foo.com: 
        database3.asia.foo.com: 
    eur:
      hosts:
        application2.eur.foo.com: 
        database2.eur.foo.com: 
    us:
      hosts:
        application1.us.foo.com: 
        database1.us.foo.com: 
    business:
      children:
        application:
          hosts:
            application1.us.foo.com: 
            application2.eur.foo.com: 
            application3.asia.foo.com: 
        database:
          hosts:
            database1.us.foo.com: 
            database2.eur.foo.com: 
            database3.asia.foo.com: 
    ungrouped:
      hosts:
        backup01.foo.com: 
        backup02.foo.com: 
        backup03.foo.com: 
        backup04.foo.com: 
        backup05.foo.com: 
        monitoring1.foo.com:

And here how ansible-inventory see that ini (here we convert in yaml) :
ansible-inventory -i inventory.ini --yaml --list

all:
  children:
    asia:
      hosts:
        application3.asia.foo.com: {}
        database3.asia.foo.com: {}
    business:
      children:
        application:
          hosts:
            application1.us.foo.com: {}
            application2.eur.foo.com: {}
            application3.asia.foo.com: {}
        database:
          hosts:
            database1.us.foo.com: {}
            database2.eur.foo.com: {}
            database3.asia.foo.com: {}
    eur:
      hosts:
        application2.eur.foo.com: {}
        database2.eur.foo.com: {}
    ungrouped:
      hosts:
        backup01.foo.com: {}
        backup02.foo.com: {}
        backup03.foo.com: {}
        backup04.foo.com: {}
        backup05.foo.com: {}
        monitoring1.foo.com: {}
    us:
      hosts:
        application1.us.foo.com: {}
        database1.us.foo.com: {}

Two default groups 
all and ungrouped.
all and ungrouped always exist while they may be implicit in the inventory declaration.
all contains every host while ungrouped contains all hosts that don’t have another group aside from all.
It means that every host always belongs to at least 2 groups : all and ungrouped OR all and some other group.

inventory variables

inventory variables overview

These are variable specific to a host or group in the inventory.
We could declare custom variables (used in the playbook as we wish) or built-in variables such as connection variables to override existing values of them.

Two ways to declare them :
– add variables directly to the hosts and groups in the inventory file.
– store variables in separate host and group variable files

inventory variables defined directly inside the inventory file

Assigning a variable to one machine: host variables

Example where we declare :
– two custom variables : foo_port and foo_max_requests with distinct variable by host
– we override the ansible_user built-in variable for the host2

foo_group:
  hosts:
    host1:
      foo_port: 80
      foo_max_requests: 50
    host2:
      foo_port: 81
      foo_max_requests: 100
     ansible_user: host2

Assigning a variable to multi machines: group variables

Example where we declare :
– two custom variables : foo_port and foo_max_requests
– we override the ansible_user built-in variable

foo_group:
  hosts:
    host1:
    host2:
  vars:     
    ansible_user: host2
    foo_port: 80
    foo_max_requests: 50

inventory variables for groups and hosts externalized into specific files

Files format : YAML syntax.
The files can optionally end in ‘.yml’, ‘.yaml’ but not mandatory.

Files location : paths relative to the inventory file or the playbook file.
For example, if the inventory file is located at /home/foo/inventory.yml and contains a host named ‘super-machine’ that belongs to two groups, ‘us’ and ‘eu’, that host will use variables in YAML files at the following locations:

 /home/foo/group_vars/us 
 /home/foo/group_vars/eu
 /home/foo/host_vars/super-machine

Files added in the playbook directory
group_vars/ and host_vars/ directories may also be added to the playbook directory.
The ansible-playbook command looks for these directories in the current working directory by default.

How variables are merged ?
The order/precedence is (from lowest to highest):
– all group (because it is the ‘parent’ of all other groups)
– parent group
– child group
– host

ansible-inventory command

Role : display or dump the configured inventory as Ansible sees it.
General syntax :
ansible-inventory [flags-not-positional...] [host|group]
Actions: One of following must be used on invocation, ONLY ONE!

  --graph               create inventory graph, if supplying pattern it must
                        be a valid group name
  --host HOST           Output specific host info, works as inventory script
  --list                Output all hosts info, works as inventory script

Examples
List hosts of the specified inventory in json format :
ansible-inventory -i inventory.ini --list

List hosts of the specified inventory in yaml format :
ansible-inventory -i inventory.ini --list --yaml

Output a graph of the specified inventory :
ansible-inventory -i inventory.ini --graph

Output a graph of the specified inventory for a specific group (here us) :
ansible-inventory -i inventory.ini --graph us