Host and inventory

The Host, Group, and InventoryData classes are the data model for "who Ansible can reach and what it knows about them". They sit beneath the inventory plugins, which populate them, and feed InventoryManager, which exposes them.

Files

File	Class	Lines
lib/ansible/inventory/host.py	Host	110
lib/ansible/inventory/group.py	Group	220
lib/ansible/inventory/data.py	InventoryData	280
lib/ansible/inventory/manager.py	InventoryManager	805
lib/ansible/inventory/helpers.py	misc	65

Host

A Host is a named target the controller can address. It has:

• name — the inventory hostname.
• address — the actual address used to connect (defaults to name; can be overridden by ansible_host).
• vars — host-specific variables.
• groups — list of Group objects this host belongs to.
• implicit — True for the auto-created localhost/127.0.0.1 host.

Host.serialize() and deserialize() produce a JSON-friendly representation, used when crossing the worker-process boundary.

The hostname is matched against patterns in --limit and play hosts: patterns. The matching rules are in lib/ansible/inventory/manager.py:_match_one_pattern.

Group

A Group is a named collection of hosts (and possibly child groups). It has:

• name — the group name.
• hosts — list of direct member Hosts.
• child_groups — list of subgroups.
• parent_groups — list of parent groups.
• vars — group-level variables.

The implicit groups all and ungrouped exist in every inventory. Every host is in all. Hosts not in any user-defined group are in ungrouped.

Group nesting is implemented via parent_groups/child_groups lists. Group.get_hosts() returns the host list including transitively-included children.

InventoryData

InventoryData is the central database: a flat dict of hosts and a flat dict of groups, plus the implicit relationships between them. Methods:

• add_host(name, group=None, port=None) — add a host, optionally placing it in a group.
• add_group(name) — create a group.
• add_child(group, child) — make child a member of group (host or group).
• set_variable(name, var, value) — set a host or group variable.
• get_host(name) / get_group(name) / get_hosts() / get_groups_dict().

Inventory plugins call these methods directly to populate the inventory. After all sources are parsed, InventoryManager is the user-facing API — it exposes list_hosts(pattern) and friends for filtering.

InventoryManager

InventoryManager (lib/ansible/inventory/manager.py) wraps InventoryData and adds:

• Multi-source orchestration. Iterates the configured sources (-i), dispatches each through the inventory plugin chain, and merges results.
• Plugin chain. For each source, walks INVENTORY_ENABLED and asks each plugin's verify_file() until one accepts.
• Pattern matching. list_hosts(pattern) filters by hostname/group/regex/range patterns, including set algebra (webservers:!staging).
• Subset (limit) handling. --limit further restricts what list_hosts returns.
• Cache integration. Inventory plugins that opt into caching use InventoryManager._cache.

Pattern matching

Patterns are powerful and idiomatic Ansible. The grammar supports:

• Plain names: web01.
• Group names: webservers.
• The all and ungrouped virtual groups.
• Wildcards: web*.example.com.
• Regex: ~web0[1-3].
• Slice subscript: webservers[0], webservers[0:5], webservers[-1].
• Set algebra:
  • Union (the default for comma): webservers,dbservers.
  • Difference: webservers:!staging.
  • Intersection: webservers:&production.

Implementation lives in _match_one_pattern in lib/ansible/inventory/manager.py. Patterns are processed left-to-right with the leading-character rules: : separates patterns, prefix & intersects, prefix ! excludes, prefix ~ is regex.

How variables flow off a host/group

InventoryData holds the raw vars set on hosts and groups. Resolving "what does host web01 see for variable X" is VariableManager's job, not inventory's. InventoryManager provides the host-and-group structure; VariableManager walks it and merges with all the other variable sources (defaults, role vars, set_fact, CLI vars, etc.).

The merge order for inventory-derived vars is:

1. all group vars (lowest).
2. Other group vars in dependency order — parents before children.
3. Host vars (highest within inventory).

Multiple groups with conflicting vars are resolved by group depth (deeper = higher priority) and, for groups at the same depth, group name alphabetical order. Set ansible_group_priority on a group to override.

Magic variables

A few host attributes are exposed as magic variables (always available without being explicitly set):

• inventory_hostname — the host's name.
• inventory_hostname_short — first dotted component.
• groups — dict of all groups → hosts.
• group_names — list of groups this host is in.
• hostvars — a special object that lets you query other hosts' vars.
• play_hosts (legacy), ansible_play_hosts, ansible_play_hosts_all — hosts in the current play.
• ansible_host — the address (settable via inventory).
• ansible_port, ansible_user, ansible_connection — connection settings.

The full list is in lib/ansible/vars/manager.py:_MAGIC_VARS_RESERVED and friends.

hostvars: cross-host references

hostvars lets a task on one host read another host's vars:

- debug:
    msg: "DB master is at {{ hostvars[groups['db_masters'][0]].ansible_host }}"

Implementation in lib/ansible/vars/hostvars.py:HostVars. It's a lazy mapping that, on each subscript, asks VariableManager.get_vars() for that target host. Expensive if used in tight loops; cached per task.

add_host and group_by

The add_host action (lib/ansible/plugins/action/add_host.py) and group_by action (lib/ansible/plugins/action/group_by.py) mutate inventory mid-run:

• add_host: name=newhost groups=foo — register a new host in the inventory.
• group_by: key=is_redhat_{{ ansible_distribution == 'RedHat' }} — create a new group from a host fact.

Both call InventoryManager.add_host / add_group directly, then clear_pattern_cache() so subsequent host pattern matches see the new entries.

Integration points

• Imported by: every CLI's __init__, lib/ansible/executor/playbook_executor.py, lib/ansible/executor/task_queue_manager.py, lib/ansible/vars/manager.py.
• Exposes: list_hosts(pattern, ignore_limit=False), get_groups_dict(), get_host(name), add_host, add_group, clear_pattern_cache.
• Internally uses: InventoryData, the inventory plugin chain, the cache plugin (if configured).

Entry points for modification

• Pattern grammar changes — _match_one_pattern and friends. Sensitive; many users rely on existing semantics.
• Magic var additions — lib/ansible/vars/manager.py:VariableManager.get_vars. Document in lib/ansible/keyword_desc.yml.
• Inventory data shape — Host, Group, InventoryData. Generally stable; changes here ripple into many tests.

Cross-links

• Dynamic inventory — how the data gets populated.
• Plugins → Inventory — the plugin spec.
• Apps → ansible-inventory — the inspection CLI.