What Facts Are
Facts are variables that Ansible automatically discovers about a managed host rather than variables a human explicitly defines — things like the operating system family, total memory, network interfaces, and mounted filesystems. At the start of a play, unless gather_facts: false is set, Ansible implicitly runs the ansible.builtin.setup module against every target host, which returns a large nested dictionary accessible as ansible_facts.some_key or, historically, as a flattened ansible_some_key variable.
Cricket analogy: Before a match, the pitch report team inspects the wicket's moisture and grass length and reports it to broadcasters automatically, just as Ansible's setup module inspects a host and reports facts before any tasks run.
Common Fact Namespaces
The setup module's output is deeply nested: ansible_facts['os_family'] returns 'Debian' or 'RedHat', ansible_facts['distribution'] and ansible_facts['distribution_version'] give the exact OS release, ansible_facts['default_ipv4']['address'] gives the primary IP, and ansible_facts['mounts'] returns a list of dictionaries describing every mounted filesystem with its size and free space. These facts are commonly used in when: conditionals, for example when: ansible_facts['os_family'] == 'Debian', to branch task execution based on the target's actual environment rather than assumptions baked into the playbook.
Cricket analogy: A team management app looks up a player's exact role — opener, all-rounder, wicketkeeper — before deciding batting order, similar to a playbook checking ansible_facts['os_family'] before deciding which package-manager task to run.
Custom Facts and set_fact
Beyond built-in facts, you can define custom facts on a host by placing .fact files (INI or JSON format) in /etc/ansible/facts.d/ on the managed node, which then appear automatically under ansible_facts['ansible_local'] the next time facts are gathered. Within a running play, ansible.builtin.set_fact creates a new fact-like variable on the fly from computed data, and adding cacheable: true makes that value persist into the fact cache for reuse by later plays or runs, which is useful for values derived from a registered task result that you want to reference repeatedly.
Cricket analogy: A team's analytics department adds a custom stat, like 'death-over economy rate,' that isn't part of the official scorecard but gets tracked alongside it, similar to a custom .fact file adding data beyond the built-in facts Ansible gathers.
Fact Caching for Performance
Gathering facts from scratch on every single playbook run against hundreds of hosts is slow, since it means an SSH connection and a full setup module execution per host every time. Setting fact_caching = jsonfile (or redis, memcached, etc.) along with fact_caching_connection and fact_caching_timeout in ansible.cfg lets Ansible reuse previously gathered facts within the timeout window, and combining this with gather_facts: smart or explicit gather_facts: false on plays that don't need fresh facts noticeably speeds up large-scale runs.
Cricket analogy: A broadcaster caches a player's season batting average rather than recalculating it from every historical scorecard before each highlight package, similar to Ansible caching facts instead of re-gathering them from scratch every run.
# ansible.cfg
[defaults]
gathering = smart
fact_caching = jsonfile
fact_caching_connection = /tmp/ansible_fact_cache
fact_caching_timeout = 86400
# /etc/ansible/facts.d/app.fact (on the managed node, INI format)
[general]
version = 2.4.1
environment = production
# playbook.yml
- hosts: webservers
tasks:
- name: Show OS family fact
ansible.builtin.debug:
msg: "{{ ansible_facts['os_family'] }} version {{ ansible_facts['distribution_version'] }}"
- name: Read custom local fact
ansible.builtin.debug:
msg: "App version is {{ ansible_facts['ansible_local']['app']['general']['version'] }}"
- name: Check free space and cache the result
ansible.builtin.set_fact:
disk_space_ok: "{{ (ansible_facts['mounts'] | selectattr('mount', 'equalto', '/') | first)['size_available'] > 5000000000 }}"
cacheable: trueUse gather_subset: ['!all', 'network', 'hardware'] on the setup module or gather_facts task to limit which fact categories are collected, which noticeably speeds up runs against hosts where you only need a handful of specific facts.
Facts gathered for a host are stored under hostvars for that host only. When using delegate_to to run a task on a different host, remember that ansible_facts inside that task still refers to the delegated host's own facts unless you explicitly reference hostvars['original_host'].
- Facts are automatically discovered host information, gathered by the setup module at the start of a play unless gather_facts is disabled.
- Common namespaces include ansible_facts['os_family'], ['distribution'], ['default_ipv4'], and ['mounts'].
- Custom facts placed in /etc/ansible/facts.d/*.fact on a managed node appear under ansible_facts['ansible_local'].
- set_fact creates a computed variable at runtime, and cacheable: true persists it into the fact cache.
- fact_caching (jsonfile, redis, etc.) avoids re-gathering facts from scratch on every run, saving time on large inventories.
- gather_subset lets you limit which categories of facts are collected to speed up runs that only need specific data.
- delegate_to changes which host's facts are active inside a task, which is a common source of confusion.
Practice what you learned
1. Which module does Ansible implicitly run at the start of a play to gather system facts?
2. Where do custom .fact files placed on a managed node appear once facts are gathered?
3. What does adding cacheable: true to a set_fact task do?
4. What is the primary purpose of configuring fact_caching in ansible.cfg?
5. When a task uses delegate_to to run on a different host, what do ansible_facts inside that task refer to?
Was this page helpful?
You May Also Like
Variables and Precedence
How Ansible collects variable values from more than twenty possible sources and resolves conflicts using a strict, well-defined precedence order.
Jinja2 Templating in Ansible
How Ansible uses the Jinja2 templating engine for variable substitution, filters, conditionals, and generating configuration files dynamically.
Group and Host Variables
How Ansible's group_vars and host_vars directories organize variables by inventory group and individual host, and how group nesting affects precedence.
Related Reading
Related Study Notes in DevOps
Browse all study notesNginx Study Notes
DevOps · 30 topics
DevOpsAdvanced Kubernetes Study Notes
Kubernetes · 30 topics
DevOpsAdvanced Bash Scripting Study Notes
Bash · 30 topics
DevOpsApache Kafka Study Notes
Kafka · 30 topics
DevOpsDocker & Kubernetes Study Notes
YAML · 40 topics
DevOpsCI/CD Tools & Pipelines Study Notes
YAML · 37 topics