Merging static and dynamic inventory · Ansible

Almost nobody runs a purely dynamic inventory. Real estates end up with a mixture: a provider API for the machines that come and go, and a hand-maintained file for the things the API does not know — the network appliance with no cloud record, the legacy box in a cupboard, and the list of hosts that must never be automated regardless of what any tag says.

Merging is the mechanism that makes that mixture one inventory. You met the basic form in Part IV; this lesson is about the part that only matters once one of the sources is dynamic, and about the exclusion list that has to survive the merge intact.

Groups union, variables overwrite

One sentence, and everything else in this lesson follows from it.

Group membership from all sources is combined. Variables from a later source replace the same variable from an earlier one.

Here is the merge in a directory. 10-first.yml places a host in all with two variables; 90-last.yml places the same host in a group and sets one of the same variables:

Read-only / Safethe merged result— Real output from ansible-core 2.21.3. ansible_host survived from the first file because nothing overwrote it. tier came from the last file. The host is a member of do_not_automate, which only the last file mentioned.

$ ansible-inventory -i inventory/ --host web01.example.com

{
  "ansible_host": "192.0.2.11",
  "tier": "from-last"
}

Reverse the order of the sources and the variable flips, while membership does not:

Read-only / Safesame two files, opposite order— Real output from ansible-core 2.21.3. Explicit -i flags are processed left to right, so the last -i is the last word. Group membership is identical either way, because groups are combined rather than replaced.

$ ansible-inventory -i inventory/90-last.yml -i inventory/10-first.yml --host web01.example.com

{
  "ansible_host": "192.0.2.11",
  "tier": "from-first"
}

Two ways to supply the order, and both are worth knowing:

Form	Order
`-i a.yml -i b.yml`	Left to right; the rightmost `-i` is the last word
`-i inventory/`	Lexicographic by filename within the directory

Which is why real repositories number their inventory files. 00-, 10-, 90- is not tidiness, it is the merge order made explicit.

group_vars bind to dynamic groups too

This is the question people expect to be complicated and it is not: a group_vars file matching a group the plugin invented works exactly like one matching a group you wrote.

Read-only / Safeinventory/group_vars/role_web.yml— role_web exists only because a keyed_groups entry created it. The file is still found and still applies.

service_port: 8443
managed_by: platform-team

Read-only / Safethe variables land on the members— Real output from ansible-core 2.21.3. --vars shows the group's variables on the group line and the resolved set on each host. web01 has service_port; db01, in role_db, does not.

$ ansible-inventory -i inventory/ --graph --vars

@all:
|--@ungrouped:
|--@role_web:
|  |--web01.example.com
|  |  |--{managed_by = platform-team}
|  |  |--{provider_tags = {'role': 'web', 'env': 'prod'}}
|  |  |--{service_port = 8443}
|  |--{managed_by = platform-team}
|  |--{service_port = 8443}
|--@role_db:
|  |--db01.example.com
|  |  |--{provider_tags = {'role': 'db', 'env': 'prod'}}

The catch is location, and it is the same catch as in Part IV: the group_vars directory must sit beside the inventory source, and a second group_vars tree beside the playbook is a different tree with different precedence. Putting group_vars next to an inventory directory — inventory/group_vars/ — is the arrangement that keeps one answer to “where do this group’s variables live”.

The operational consequence is worth stating: a group name from a provider tag is now also a filename in your repository. Rename the tag, and group_vars/role_web.yml matches nothing. No error, no warning; the variables just stop being applied, and the first symptom is a service configured on the wrong port.

The exclusion list that must survive everything

The reason merging matters for safety is this one file.

Every estate has machines that must not be touched by general automation: a database mid-migration, a system under a vendor support contract that voids on unexpected changes, an appliance whose configuration is managed by another team, a host frozen for a forensic investigation.

That list is the opposite of dynamic. It is decided by people, it changes rarely, and it must not be overridable by an API.

Read-only / Safeinventory/90-do-not-automate.yml— Numbered last so it is read last. Comments carry the reason and the review date, because an exclusion nobody can justify eventually gets deleted by somebody tidying up.

all:
children:
  do_not_automate:
    hosts:
      db01.example.com:
        exclusion_reason: 'vendor support contract - ticket OPS-4471'
        exclusion_review: '2026-11-01'
      legacy-app01.example.com:
        exclusion_reason: 'pending forensic hold'
        exclusion_review: '2026-09-15'

Membership unions, so those hosts are in do_not_automate no matter what any dynamic source says about them. They will also still be in role_db, env_prod and everything else the plugin put them in — the static file adds a group, it does not remove any.

Which means the exclusion does nothing until a pattern uses it:

Read-only / Safethe exclusion, applied— Real output from ansible-core 2.21.3. db01 is in the production group and is removed by the exclusion term. This is the pattern every play targeting broad groups should use.

$ ansible -i inventory/ 'production:!do_not_automate' --list-hosts

  hosts (6):
  web01.example.com
  web02.example.com
  web03.example.com
  web04.example.com
  db02.example.com
  cache01.example.com

An exclusion group is a convention, not an enforcement

Nothing in Ansible knows that do_not_automate is special. It is a group with an ordinary name, and a play whose hosts: line forgets the :!do_not_automate term reaches those hosts exactly as it reaches any other.

Three things make it real rather than decorative:

Every play that targets a broad group carries the exclusion term. Not most. A single play without it is the whole hole.
A pre-flight assertion fails the run when ansible_play_hosts_all intersects the excluded set. That converts the convention into an error message, and it is what Part XXX lesson 8 builds.
CI greps for the pattern. A check that fails any hosts: line naming all or a top-level environment group without an exclusion term is twenty lines of script and catches the omission at review time.

Without at least the second of those, do_not_automate documents an intention rather than enforcing one.

Ordering a real inventory directory

Read-only / Safea layout that survives contact with a team

inventory/
00-static-core.yml          # hosts no API knows about
10-cloud-eu.yml             # plugin config: provider, European estate
11-cloud-us.yml             # plugin config: provider, American estate
20-constructed.yml          # derived groups; sees 00-11 above
90-do-not-automate.yml      # the exclusion list, read last
group_vars/
  role_web.yml
  env_prod.yml
  do_not_automate.yml       # e.g. a marker variable the guardrail asserts on

Four properties that layout buys:

The merge order is readable without running anything. Somebody new can tell which file has the last word by looking at the names.
Constructed groups come after the sources they derive from, so the visibility rule is satisfied structurally rather than by luck.
The exclusion list is unambiguously last, so no dynamic source can overwrite a variable it sets.
group_vars sits inside the inventory directory, so there is one place a group variable can live and one answer when somebody asks where it came from.

Under the hood

The merge is not a file-level operation. Ansible builds one in-memory InventoryData object and each source, in turn, adds to it — hosts, groups, and variables — through the same API a plugin uses.

That explains both halves of the rule. add_child on a group is additive by nature: you cannot express “remove this host from that group” through it, which is why membership only ever grows. Variables go through a dictionary update, and a dictionary update replaces.

Two details follow that are easy to trip on.

There is no “remove” in the model. A later source cannot take a host out of a group an earlier source put it in. The only way to express removal is at pattern time, with !. This is precisely why the exclusion list works by adding a group rather than by subtracting membership, and why the subtraction has to be repeated in every pattern.

Variable values are replaced, not merged. If 10-cloud.yml sets app_config: {port: 80, tls: false} and 90-overrides.yml sets app_config: {tls: true}, the resulting value is {tls: true} — port is gone. Whether dictionaries merge instead is governed by the hash_behaviour setting, whose default is replace and which the documentation advises against changing, because switching it changes the meaning of every variable in the repository at once.

What happens if a dynamic source and a static file disagree about a host address?

The last source wins, and this is a genuinely common way to be surprised.

A static file was written years ago with ansible_host: 192.0.2.11 for a machine that has since been rebuilt. The cloud plugin returns the current private address and composes ansible_host from it. Which one Ansible connects to depends entirely on file ordering.

If the static file sorts last — zz-legacy.yml, or an explicit -i after the plugin config — the stale address wins and every run against that host is unreachable. The error says “connection timed out”, which sends people to look at the network, at security groups, at SSH. The actual cause is a value from an inventory file, visible immediately:

ansible-inventory --host web01.example.com

The general habit is worth the ten seconds. When a host behaves inexplicably, print its resolved variables before you investigate anything on the host, because the merge is the one part of the system where two correct-looking files quietly produce a wrong answer.

The design fix is to decide, once, which source owns connection details, and remove the field from every other source rather than relying on ordering to break the tie.

Groups union, variables overwrite

group_vars bind to dynamic groups too

The exclusion list that must survive everything

Ordering a real inventory directory

Knowledge check