Magic Variables

Magic variables are values Ansible sets automatically that describe the run itself — which host this task is on, what groups exist, who else is in the play — and they are how one host reaches across to another's data. hostvars, groups, group_names, inventory_hostname, and ansible_play_hosts are the ones you use constantly.

The signature move is a web host reading hostvars['db1.larkspur.io']['ansible_facts']['default_ipv4']['address'] to template the database's IP into its own config — without ever running a task on the database. That single expression is how a push-based, stateless tool assembles a topology: each host reads the others' live facts, and no shared store sits in the middle.

inventory_hostname and the Short Form

inventory_hostname is the name this host has in the inventory — web1.larkspur.io — and it is the value you template into per-host config files and log lines to identify the box. It answers "who am I" for the current task. inventory_hostname_short is the part before the first dot, web1, useful when a config wants the bare hostname rather than the fully qualified name.

One distinction matters: inventory_hostname is the inventory name, which is not always the connection address. A host whose inventory entry sets ansible_host to a separate IP or DNS name is reached at ansible_host but named by inventory_hostname. Templating the wrong one — the inventory label where you needed the SSH target — points config at a name that may not resolve where the application runs.

hostvars — Reach Into Any Host's Data

hostvars is a dict keyed by every host's inventory name, exposing that host's variables and gathered facts. hostvars['db1.larkspur.io']['ansible_facts']['default_ipv4']['address'] lets a web host template the database's real IP into app.env — the canonical cross-host read. The web host never runs a task on db1; it simply reads db1's facts out of hostvars, which is populated for every host Ansible knows about in the run.

# templates/app.env.j2 — rendered on each web host
DATABASE_HOST={{ hostvars['db1.larkspur.io']['ansible_facts']['default_ipv4']['address'] }}
DATABASE_PORT=5432
BIND={{ ansible_facts['default_ipv4']['address'] }}:{{ larkspur_web_nginx_port }}

The catch is that db1's facts must actually be present — either db1 was gathered in this same run, or its facts are in the cache. Reach for a host that was never gathered and the hostvars lookup returns undefined, which is the exact problem fact caching in Topic 31 exists to solve. The cross-host read is the reason caching matters at all.

groups and group_names

These two are constantly confused, and keeping them straight is half of using magic variables well. groups is a dict of every group to its member hostnames: groups['web'] is the list of all web hosts, which you iterate to template "all the web servers" into an HAProxy backend or an nginx upstream block. It is the whole-inventory view — every group, every member.

group_names is the opposite direction: the list of groups this host belongs to. On web1 it reports ['web', 'larkspur'], and you use it in a when: to branch by role — when: "'web' in group_names" runs a task only on web hosts. Reaching for groups when you meant group_names — testing membership with the all-groups dict instead of this host's own list — is the classic mix-up, and it usually fails silently with the wrong branch taken.

ansible_play_hosts and ansible_play_batch

ansible_play_hosts is the set of hosts still active in the current play — those that haven't failed and dropped out. ansible_play_batch is the current serial batch, the wave of hosts being processed right now under a rolling configuration. Both shrink as hosts drop out, so they describe the live state of the play rather than its original target list.

These matter for rolling deploys, where you template "the hosts in this wave" into a load-balancer drain step or check who is left after some hosts failed. The trap is treating ansible_play_hosts as the full original target — it only contains hosts still active, so a host that failed earlier silently disappears from any list built from it. When you need the complete static target list regardless of failures, use groups, not ansible_play_hosts.

The Cross-Host Read in Practice

Larkspur's nginx upstream block iterates groups['web'] and resolves each member's IP through hostvars, producing a backend list of every web host's real address. The app's app.env reads db1's address the same way. This is how a push-based, stateless tool assembles a topology — each host reads the others' live facts at template time, and there is no service-discovery store or shared state to consult.

The pattern is worth naming because it replaces a whole category of infrastructure. Instead of Consul or a config server handing out peer addresses, the run gathers every host's facts and exposes them through hostvars, and a template stitches the topology together from facts that are true this run. The cost is that every host whose data you read must be gathered or cached — which is precisely why the next topic exists.