Inventory Files Explained

An inventory is the file — or dynamic data source — that tells Ansible which hosts to manage and how to connect to them. Every Ansible command needs an inventory: without one, Ansible has no targets to run against. Inventories can be as simple as a single IP address in a text file, or as sophisticated as a live query against a cloud provider's API that returns thousands of servers grouped by region, environment, and role. Mastering inventory is essential because it is the bridge between your automation code and your real infrastructure.

Static Inventory Formats

A static inventory is a file you write and maintain by hand. Ansible supports two formats: INI and YAML. Both express the same information — they are purely a matter of preference and team convention. INI is more compact; YAML is more explicit and integrates naturally with the rest of your Ansible project.

INI inventory — inventory.ini

# Ungrouped hosts — reachable by Ansible but not in any named group
192.168.1.5

# A group called webservers
[webservers]
web01.example.com
web02.example.com ansible_port=2222   # override SSH port for this host only

# A group called databases
[databases]
db01.example.com ansible_user=dbadmin
db02.example.com

# A group of groups — 'production' contains both webservers and databases
[production:children]
webservers
databases

# Variables that apply to every host in the webservers group
[webservers:vars]
http_port=80
nginx_version=1.25

YAML inventory — inventory.yml

# The top-level key 'all' is mandatory — it is the implicit parent of every group
all:
  children:

    webservers:
      hosts:
        web01.example.com:
        web02.example.com:
          ansible_port: 2222    # override SSH port for this host only
      vars:
        http_port: 80
        nginx_version: "1.25"

    databases:
      hosts:
        db01.example.com:
        db02.example.com:
      vars:
        db_port: 5432

    production:
      children:
        webservers:
        databases:

Groups, Children, and the all Group

Every inventory has two implicit groups that always exist: all — which contains every host in the inventory — and ungrouped — which contains hosts not assigned to any named group. Beyond these, you define your own groups to organise hosts by role, environment, location, or any other dimension that matters to your automation.

A group can contain hosts directly or contain other groups as children. A host can belong to multiple groups simultaneously. When you run a playbook against production, Ansible resolves the full member list — including all hosts in webservers and databases — automatically.

Host Variables and Group Variables

Variables can be attached directly to hosts or groups inside the inventory file — or, for larger projects, stored in dedicated host_vars/ and group_vars/ directories. This separation keeps your inventory clean and your variables easy to find.

Recommended structure — group_vars/ directory

# Project directory layout — variables live outside the inventory file
myproject/
├── ansible.cfg
├── inventory.ini
├── site.yml
├── group_vars/
│   ├── all.yml          # variables that apply to every host
│   ├── webservers.yml   # variables for the webservers group only
│   └── databases.yml    # variables for the databases group only
└── host_vars/
    └── web01.yml        # variables for web01 only (overrides group_vars)

Special Connection Variables

Ansible has a set of reserved variable names — called magic variables — that control how it connects to each host. These can be set inline in the inventory or in host_vars/ files to override the global defaults in ansible.cfg.

Verifying Your Inventory

Before running any playbook, use ansible-inventory to inspect what Ansible sees in your inventory file. This is the fastest way to catch typos, misconfigured groups, or missing variables before they cause a failed run.

# List all hosts and groups in a human-readable tree format
ansible-inventory -i inventory.ini --graph

# Show the full inventory as JSON — reveals every variable resolved per host
ansible-inventory -i inventory.ini --list

# Show details for a single host — all variables that will apply to it
ansible-inventory -i inventory.ini --host web01.example.com

# Output of --graph
@all:
  |--@ungrouped:
  |  |--192.168.1.5
  |--@production:
  |  |--@webservers:
  |  |  |--web01.example.com
  |  |  |--web02.example.com
  |  |--@databases:
  |  |  |--db01.example.com
  |  |  |--db02.example.com

Dynamic Inventory

A dynamic inventory is a script or plugin that generates the host list at runtime by querying an external source — a cloud provider API, a CMDB, or any other system that knows what servers exist. Instead of maintaining a hand-edited file, Ansible calls the script before each run and receives a fresh, up-to-date list of hosts and their metadata.

Dynamic inventory is the standard approach in cloud environments where servers are constantly being created, scaled, and terminated. You never want to maintain a static inventory for an auto-scaling group — by the time you update it, the server list has already changed. Ansible ships with built-in dynamic inventory plugins for AWS, GCP, Azure, VMware, OpenStack, and many others.