Which facts you can trust · Ansible

The word “fact” is doing a lot of persuasive work.

A fact is a value a fact module produced by asking the host a question, at one moment, through one mechanism. Some of those mechanisms are as close to ground truth as you can get. Others are a best guess from a heuristic that was written before the situation you are in existed. They arrive in the same dictionary, formatted identically, with nothing to distinguish them.

Treating all 121 of them as equally authoritative is how a play ends up choosing dnf on a Debian host, or sizing a JVM heap from a memory figure that was true before the VM was resized.

The reliability ranking

Facts sort into four bands. The band matters more than the individual fact, because it tells you what kind of mistake you are exposed to.

Band 1: read directly from a file the OS maintains

ansible_facts.distribution, distribution_version, distribution_release, os_family. These come from /etc/os-release and its predecessors. The fact even tells you which file it used:

Read-only / Safethe distribution collector shows its working— Reads only the distribution collector. Note the file_path and file_parsed keys - the fact records where it got the answer and whether parsing succeeded.

$ ansible localhost -m ansible.builtin.setup -a "gather_subset=!all,!min,distribution"

localhost | SUCCESS => {
  "ansible_facts": {
      "ansible_distribution": "Ubuntu",
      "ansible_distribution_file_parsed": true,
      "ansible_distribution_file_path": "/etc/os-release",
      "ansible_distribution_file_variety": "Debian",
      "ansible_distribution_major_version": "26",
      "ansible_distribution_release": "resolute",
      "ansible_distribution_version": "26.04",
      "ansible_os_family": "Debian"
  },
  "changed": false
}

distribution_file_parsed: true is the fact telling you it is confident. On an exotic or damaged host it comes back false and the distribution values are a fallback guess — which is a check worth making in an assertion before you branch on the distribution across a mixed fleet.

These are the most trustworthy facts available and they are still only as true as /etc/os-release, which is a text file that an in-place distribution upgrade rewrites and a badly built container image sometimes inherits from the wrong base.

Band 2: stable identity that outlives a reboot

ansible_facts.machine_id, ansible_facts.architecture, ansible_facts.userspace_bits, the SSH host key facts.

machine_id is the one worth knowing about. It comes from /etc/machine-id, it is stable across reboots, and it is not stable across cloning — a VM template that baked in a machine-id produces a fleet of hosts sharing one identity. That is a real condition that shows up as strange behaviour in anything keyed on it, and Ansible will report the duplicate value without comment.

Band 3: current state, true right now, possibly not in five minutes

Memory, CPU count, mounts, block devices, addresses, uptime, date.

Read-only / Safefacts that describe a moment— Hardware and network facts read the current state of the machine. Everything here can change without the host being rebuilt.

$ ansible localhost -m ansible.builtin.setup -a "filter=ansible_memtotal_mb,ansible_processor_vcpus,ansible_processor_cores"

localhost | SUCCESS => {
  "ansible_facts": {
      "ansible_memtotal_mb": 47145,
      "ansible_processor_cores": 12,
      "ansible_processor_vcpus": 12
  },
  "changed": false
}

These are correct and they are also the ones that produce quiet damage, because the mistake is not reading them — it is persisting a decision made from them. A template that writes a JVM heap size computed from memtotal_mb records that number in a config file. The VM is resized. The config still says the old number, and nothing re-runs until someone notices the process is undersized on a machine with twice the RAM.

The defence is to write the rule into the config rather than the result where the target supports it, and where it does not, to run the play that recomputes it as part of the resize procedure. That is a runbook problem, not a templating problem.

`processor_cores` is not the number you want, usually

Four processor facts are returned and they mean four different things:

Fact	Meaning
`processor_count`	Physical sockets
`processor_cores`	Cores per socket
`processor_threads_per_core`	SMT threads per core
`processor_vcpus`	Total logical CPUs the OS can schedule on

For “how many workers should this service run”, you almost always want processor_vcpus. Using processor_cores on a two-socket machine sizes the service for half the box; on a machine with SMT it halves it again.

On the host measured above, processor_count is 1 and processor_cores is 12, so both happen to be wrong in a way that is invisible until the play meets a two-socket server.

Band 4: heuristics and best guesses

ansible_facts.virtualization_type, virtualization_role, service_mgr, pkg_mgr, is_chroot.

These are inferred, not read. The virtualisation facts in particular work by looking for signatures — hypervisor strings in DMI data, device names, cgroup contents — and they get less reliable the more layers of abstraction sit between the kernel and the metal.

Read-only / Safean inferred fact reporting something odd— Virtualisation facts on a KVM guest. Both the guest and host technology lists report kvm, which is what nested or nested-capable virtualisation looks like from inside.

$ ansible localhost -m ansible.builtin.setup -a "filter=ansible_virtualization_*"

localhost | SUCCESS => {
  "ansible_facts": {
      "ansible_virtualization_role": "guest",
      "ansible_virtualization_tech_guest": [
          "kvm"
      ],
      "ansible_virtualization_tech_host": [
          "kvm"
      ],
      "ansible_virtualization_type": "kvm"
  },
  "changed": false
}

That output is real, from the machine this lesson was written on. It reports the host as a KVM guest and simultaneously reports KVM host technology — because the machine is a guest that itself has KVM available. Neither value is wrong. A conditional written as when: ansible_facts.virtualization_role == 'host' to mean “this is bare metal” would be correct here by luck, and wrong on a bare-metal host with KVM installed.

The rule for band 4: do not branch a change on an inferred fact when inventory could answer the question instead. Whether a host is a hypervisor is a fact about your estate that you know, and it belongs in a group. Lesson 7 of Part XV makes this argument in full.

Absent is not the same as empty

The most common fact-related failure is not a wrong value. It is reading a key that is not there, or is there and empty.

Three distinct states, which conditionals routinely conflate:

State	Example	`is defined`
Never collected	`mounts` when `gather_subset` excluded `hardware`	false
Collected, no data	`default_ipv4` on a host with no default route	true
Collected, has data	`default_ipv4` on a normal host	true

The middle row is the trap. default_ipv4 on a host with no default route is {} — defined, empty, and ansible_facts.default_ipv4.address raises an undefined error on the next line.

Read-only / Safetesting for the thing you are about to read— The first form tests the parent and fails on an empty dictionary. The second tests the value itself and holds up.

# Fragile: passes on a host where default_ipv4 is an empty dict,
# then fails on the next line.
- name: Register the address
ansible.builtin.debug:
  msg: "{{ ansible_facts.default_ipv4.address }}"
when: ansible_facts.default_ipv4 is defined

# Holds up: tests the exact value being read.
- name: Register the address
ansible.builtin.debug:
  msg: "{{ ansible_facts.default_ipv4.address }}"
when: ansible_facts.default_ipv4.address is defined

# Better still where a fallback is meaningful: no conditional at all.
- name: Register the address
ansible.builtin.debug:
  msg: "{{ ansible_facts.default_ipv4.address | default('none') }}"

The default() filter is the right answer more often than a when:, because it puts the fallback next to the value instead of in a separate line that a later edit can get out of step with.

Facts with a shape that changes

Some facts are not a value but a structure, and the structure differs between hosts. ansible_facts.selinux is the standard example:

Read-only / Safea fact whose shape depends on the host— On a host without SELinux the fact is a one-key dictionary. On a host with it enabled the same fact carries mode, type, policyvers and config_mode.

$ ansible localhost -m ansible.builtin.setup -a "filter=ansible_selinux,ansible_service_mgr,ansible_pkg_mgr,ansible_fips"

localhost | SUCCESS => {
  "ansible_facts": {
      "ansible_fips": false,
      "ansible_pkg_mgr": "apt",
      "ansible_selinux": {
          "status": "disabled"
      },
      "ansible_service_mgr": "systemd"
  },
  "changed": false
}

ansible_facts.selinux.mode does not exist on this host. It exists on a RHEL host with SELinux enabled. A play that reads it works perfectly across the RHEL half of a mixed fleet and fails on the Debian half — which is the worst kind of failure, because it passed review, it passed staging if staging was RHEL, and it fails on part of production.

The habit that catches this class: when you write a conditional on a fact, ask which host in your fleet does not have it. If you cannot name one, you have not looked at a wide enough sample of the fleet.

Under the hood

Facts are produced by fact collectors — small classes inside ansible-core, one per subset. Each collector knows how to find its information on the platforms it supports and returns a dictionary.

That architecture explains most of the behaviour in this lesson.

A collector that finds nothing to report returns an empty structure rather than omitting the key, which is why default_ipv4 is {} rather than absent. A collector that is not run at all contributes no keys, which is why the same fact is absent when gather_subset excluded it. Same fact, two different absences, distinguished only by whether the collector ran.

Collectors also fail independently. One collector raising an error or hitting gather_timeout does not stop the others; the facts it would have produced are simply missing from the result. That is why you can get a run where most facts are present and one family of them is mysteriously absent on a subset of hosts, with no failure to point at.

The practical consequence: a missing fact is not evidence of anything about the host. It might mean the host lacks the feature, or that the collector was excluded, or that it timed out. Reading ansible_facts.gather_subset in the result tells you which of those it was.

What happens if you assert on facts before acting on them?

You get failures at the top of the play instead of halfway through it, and that is worth a great deal.

- name: Preconditions the rest of this play depends on
  ansible.builtin.assert:
    that:
      - ansible_facts.distribution_file_parsed | bool
      - ansible_facts.os_family in ['Debian', 'RedHat']
      - ansible_facts.default_ipv4.address is defined
    fail_msg: >-
      This host does not meet the assumptions this play makes about
      facts. Investigate before re-running.

A host failing that assertion is removed from the play before any task changed it. A host that instead fails on task nine has had eight tasks applied and is in a state nobody designed.

The cost is that you have to state your assumptions, which is the actual benefit. Guardrails as a design tool get a full part later in the course; the fact-specific version is worth adopting immediately, because facts are the assumptions most plays make without noticing.

Knowledge check

Why this matters

Automation acts on evidence, and the quality of the evidence sets the ceiling on the quality of the automation. A play is a chain of inferences: this fact says Debian, so use apt; this fact says 48 GB, so size the heap at 24. Every link in that chain is only as strong as the fact under it.

What makes this operationally serious rather than philosophical is that Ansible presents all facts identically. There is no confidence value, no marker distinguishing “read from a file the kernel maintains” from “guessed from a DMI string”. The judgement about which is which has to come from you, and it has to come before you write the conditional, because afterwards the play looks equally reasonable either way.

Rank the fact before you branch on it. And when a decision matters and the fact is a band-4 guess, put the decision in the inventory where a human made it deliberately and a reviewer can see it.