Custom facts with facts.d · Ansible

Everything so far has been Ansible asking a host questions from a fixed list. Custom facts turn that around: the host gets to volunteer information that no fact module knows how to ask for.

The mechanism is small. The interesting part is deciding what belongs there, because the obvious uses are mostly bad ones and the good use is narrow and genuinely valuable.

The mechanism

Drop a file ending in .fact into a directory on the managed node. The setup module reads that directory and puts the contents under ansible_facts.ansible_local, keyed by filename without the extension.

The directory defaults to /etc/ansible/facts.d, and the fact_path play keyword overrides it.

Two static files on a host:

Read-only / Safe/etc/ansible/facts.d/exception.fact— An INI-format fact file. Sections become the first level of the dictionary.

[change_control]
frozen = true
ticket = CHG-004417
reason = pending storage migration

Read-only / Safe/etc/ansible/facts.d/inventory.fact— A JSON-format fact file. JSON preserves types, which matters more than it looks.

{
"owner": "platform-team",
"tier": "gold"
}

And what a play sees:

Read-only / Safethe ansible_local namespace, real output— Gathers only the local collector and prints the resulting namespace. Filenames become the first key; INI sections and JSON objects become the structure beneath.

$ ansible-playbook local.yml

TASK [The ansible_local namespace] *********************************************
ok: [localhost] => {
  "ansible_facts.ansible_local": {
      "exception": {
          "change_control": {
              "frozen": "true",
              "reason": "pending storage migration",
              "ticket": "CHG-004417"
          }
      },
      "inventory": {
          "owner": "platform-team",
          "tier": "gold"
      }
  }
}

The play that produced it:

Read-only / Safelocal.yml— fact_path is a play keyword. gather_subset restricted to local means this play gathers custom facts and nothing else, which is cheap enough to run against a whole fleet.

- name: Read host-declared facts
hosts: all
gather_facts: true
fact_path: /etc/ansible/facts.d
gather_subset:
  - '!all'
  - '!min'
  - local
tasks:
  - name: The ansible_local namespace
    ansible.builtin.debug:
      var: ansible_facts.ansible_local

Note gather_subset: local. Custom facts are their own collector, so a play that only needs them can skip everything else. That combination — !all, !min, local — is a fleet-wide survey of host-declared state that costs almost nothing.

Read-only / Safebranching directly on an INI fact— A conditional reading the string true from an INI fact file. In 2.21 a non-boolean conditional result is an error rather than a silently-true condition.

$ ansible-playbook frozen.yml

TASK [Type of the INI fact] ****************************************************
ok: [localhost] => {
  "msg": "frozen is a str with value true"
}

TASK [Branch on it directly] ***************************************************
[ERROR]: Task failed: A 'when' expression failed: Conditional result (True)
was derived from value of type 'str'. Conditionals must have a boolean result.

fatal: [localhost]: FAILED! => {"msg": "Task failed: A 'when' expression
failed: Conditional result (True) was derived from value of type 'str'.
Conditionals must have a boolean result."}

This is a genuine improvement, and it is worth understanding why. On older versions that conditional was silently true — because a non-empty string is truthy — so a fact file saying frozen = false would have enabled the change it was written to block. The failure mode was a change freeze that did the opposite of what it said. Now it fails loudly instead.

Two ways to make it correct:

Read-only / Safeboth forms work; prefer the second— Casting at the point of use, versus removing the ambiguity by using JSON, which has real types.

# 1. Cast at the point of use. Works with INI facts.
- name: Skip when the host declares a freeze
ansible.builtin.debug:
  msg: "would deploy"
when: not (ansible_facts.ansible_local.exception.change_control.frozen | bool)

# 2. Use JSON for the fact file. Then frozen is a real boolean
#    and the conditional needs no filter at all.
- name: Skip when the host declares a freeze
ansible.builtin.debug:
  msg: "would deploy"
when: not ansible_facts.ansible_local.exception.change_control.frozen

The second is better. A | bool sprinkled through a repository is a maintenance tax and it is easy to forget on the one conditional that matters. Write custom fact files as JSON. The types survive, and Part XV lesson 1 shows how much of the conditional-logic pain in Ansible comes from types that were lost somewhere upstream.

Static and executable fact files

A .fact file that is executable is run, and its stdout is parsed as JSON or INI. A file that is not executable is read directly.

That distinction is the whole API, and it is decided by the execute bit alone. A fact script that loses its execute bit does not error — the setup module reads the script source, fails to parse it, and the fact is missing or garbage.

Read-only / Safean executable fact script— Prints a JSON object on stdout. Must be executable, must be fast, must never fail in a way that produces partial output.

#!/bin/sh
# /etc/ansible/facts.d/app.fact  (mode 0755)
set -eu
VERSION=$(cat /opt/app/VERSION 2>/dev/null || echo unknown)
printf '{"version": "%s", "config_generation": %s}\n' \
"$VERSION" \
"$(cat /opt/app/generation 2>/dev/null || echo 0)"

Executable facts are powerful and they are also the part of this mechanism that causes operational problems, so they come with rules.

They run on every gather. Every play, every host, every run. A fact script that takes two seconds adds two seconds per host to every run in the estate. Keep them to reading a file and printing.

They run as the connecting user, before become. A script needing root to produce its answer will not get it. Design the answer to be readable by the automation user, or the fact does not work.

A failure is silent. A script that exits non-zero, or prints anything that is not valid JSON or INI, produces a missing or malformed key rather than a task failure. Combine that with a conditional and you have a play that quietly does the wrong thing on the hosts where the script broke.

They are a place code hides. A shell script on 500 hosts, deployed by some other mechanism, whose output your automation branches on, is code you now maintain in two places with no shared review. If the answer can come from a file, use a static file.

Blast radius: who can write a fact file?

Anyone who can write to /etc/ansible/facts.d on a managed node can change what your automation believes about that host, and therefore what it does to it.

If a play skips a change when ansible_local.exception.change_control.frozen is true, then write access to that directory is the ability to opt a host out of fleet-wide automation — including a security patch run.

That is not a reason to avoid the mechanism. It is a reason to treat the directory as automation-owned configuration:

Root-owned, mode 0755 on the directory, 0644 on static facts.
Deployed by the automation itself, from the repository, so the content is reviewed and the file is a known artefact rather than something someone wrote by hand at 2am.
Reported on. A survey play that prints ansible_local across the fleet is how you find the host that has been exempting itself for eight months.

The good use: a host that declares a documented exception

Here is the case that justifies the whole mechanism.

A fleet-wide patching run must skip one database host, because a storage migration is in progress and a reboot would be a data-loss event. You have three places to record that.

In the playbook. A when: inventory_hostname != 'db07' in the patching role. Terrible: it is invisible to anyone reading the inventory, it will still be there in a year, and it puts a specific host’s name in shared code.

In the inventory. A host_vars/db07.yml with patching_exempt: true. Good, and for most exceptions this is the right answer — Part XIII’s layering rule says host_vars records exceptions and nothing else, and this is exactly that.

On the host. A .fact file the host carries with it.

The third is right when the exception is a property the host knows about and the inventory would have to be told. The storage migration was started by a database engineer at the console. They can drop a fact file as part of the runbook step that starts the migration, and remove it as part of the step that finishes it. The exception has the same lifetime as the condition that caused it.

Read-only / Safethe play that respects it— A guard at the top of a patching play. The assertion is deliberately loud - a skipped host should be a visible outcome, not a silent one.

- name: Patch the fleet
hosts: all
gather_subset:
  - '!all'
  - '!min'
  - local
  - distribution
tasks:
  - name: Report hosts that have declared a change freeze
    ansible.builtin.debug:
      msg: >-
        SKIPPING {{ inventory_hostname }}:
        {{ ansible_facts.ansible_local.exception.change_control.reason }}
        (ticket {{ ansible_facts.ansible_local.exception.change_control.ticket }})
    when: ansible_facts.ansible_local.exception.change_control.frozen
          | default(false) | bool

  - name: Apply pending updates
    ansible.builtin.package:
      name: '*'
      state: latest
    when: not (ansible_facts.ansible_local.exception.change_control.frozen
               | default(false) | bool)

Two details make this work rather than merely run.

| default(false) handles the overwhelming majority of hosts, which have no such fact file at all. Without it the play fails on every unexempted host — the opposite of intended.

The reason and ticket are printed, not just consulted. A skip that leaves no trace is indistinguishable from a bug. A skip that prints the ticket number is an auditable decision, and it also means that when the storage migration finished three weeks ago and nobody removed the file, the ticket number in the run output is what makes someone notice.

Under the hood

ansible_local is populated by the local fact collector inside the setup module. It lists fact_path, and for each file ending in .fact it either executes it (if the execute bit is set) or reads it, then tries JSON first and INI second.

There is no schema and no validation. Whatever parses becomes facts.

The naming is worth pausing on, because two similar-looking things are unrelated. ansible_local is host-declared custom facts. The local connection plugin runs tasks on the controller. They share a word and nothing else — a host gathered over SSH still gets ansible_local facts from its own /etc/ansible/facts.d, read on that host.

One more consequence of “no validation”: the filename becomes a key directly. A file called my-app.fact produces the key my-app, which dot notation cannot reach — ansible_local.my-app parses as a subtraction. It has to be ansible_local['my-app']. Name fact files with underscores.

What happens if a fact script starts returning garbage?

Nothing visible, which is the problem.

The local collector parses what it gets. If the output is not valid JSON or INI, the key is missing or partially populated. There is no task failure, no warning in the default callback, and the run proceeds with a fact your plays are branching on quietly absent.

Where that becomes an incident is a conditional with a default(). when: ansible_local.app.maintenance | default(false) | bool reads as “skip during maintenance”, and if the fact script breaks, the default fires and the host is treated as not in maintenance. The safety mechanism fails open.

Two defences worth building in from the start:

Fail closed for anything protective. If the fact is a guard, an absent fact should stop the run for that host rather than permit it. An assert that the fact is present, before the guard that consults it, is four lines and turns a silent wrong answer into a loud one.
Survey the fleet. A scheduled play that gathers only gather_subset: local and reports where ansible_local is empty or malformed is cheap, and it is the only way to find a fact script that broke on 30 hosts three weeks ago.

Knowledge check

Why this matters

Automation at scale needs a way for a host to say “not me, and here is why”. Without one, the alternatives are all worse: someone edits the playbook, someone runs with a --limit that excludes the host and forgets to remove it, or someone simply does not run the automation that week.

A host-declared exception with a ticket number attached is the version of that conversation which leaves evidence. It has a reason, an owner, a lifetime, and it shows up in the run output where somebody will see it.

The failure mode is also worth carrying forward. Exception mechanisms accumulate. The fact file for a storage migration that finished in March is still exempting that host from patching in November, and nothing will tell you unless the exception is reported every time it fires. Print the reason, print the ticket, and survey the fleet for them on a schedule. An exception nobody can see is indistinguishable from a bug.