Working with Facts
1. Gathering Facts
| Fact | Description | Example Value |
|---|---|---|
| ansible_fqdn | Fully qualified domain name of the host | web01.example.com |
| ansible_hostname | Hostname of the host | web01 |
| ansible_os_family | Operating system family (e.g., RedHat, Debian) | RedHat |
| ansible_distribution | OS distribution name | CentOS |
| ansible_distribution_version | OS distribution version | 8.5 |
| ansible_kernel | Kernel version of the host | 4.18.0-348.el8.x86_64 |
| ansible_memory_mb | Total memory in MB | 4096 |
| ansible_processor_count | Number of CPU cores | 4 |
| ansible_interfaces | List of network interfaces | ["lo", "eth0"] |
| ansible_default_ipv4 | Default IPv4 address information | |
Example: Using gathered facts in a task
- name: Display OS info
debug:
msg: "OS is {{ ansible_distribution }} version {{ ansible_distribution_version }}"
- name: Display memory info
debug:
msg: "Total RAM is {{ ansible_memory_mb.real }} MB"
Note: Facts are gathered automatically when an Ansible playbook runs unless
gather_facts: false is set in the playbook or host configuration.
2. Accessing Ansible Facts
| Fact | Description | Example Usage |
|---|---|---|
| ansible_fqdn | Fully qualified domain name of the host | {{ ansible_fqdn }} |
| ansible_hostname | Hostname of the host | {{ ansible_hostname }} |
| ansible_os_family | Operating system family (e.g., RedHat, Debian) | {{ ansible_os_family }} |
| ansible_distribution | Operating system distribution name (e.g., Ubuntu, CentOS) | {{ ansible_distribution }} |
| ansible_kernel | Kernel version of the host | {{ ansible_kernel }} |
| ansible_memory_mb | Total memory in MB | {{ ansible_memory_mb.total }} |
| ansible_interfaces | List of network interfaces | {{ ansible_interfaces }} |
| ansible_all_ipv4_addresses | List of all IPv4 addresses | {{ ansible_all_ipv4_addresses }} |
Example: Using Facts in a Playbook
- name: Display host facts
hosts: all
tasks:
- name: Show FQDN and OS family
debug:
msg: "Host: {{ ansible_fqdn }}, OS: {{ ansible_os_family }}"
Example: Using Facts in a Template
<h1>{{ ansible_hostname }}</h1>
<p>Kernel: {{ ansible_kernel }}</p>
<p>Memory: {{ ansible_memory_mb.total }} MB</p>
3. Using Hardware Facts
| Fact | Description | Example Value |
|---|---|---|
| ansible_architecture | System architecture (e.g., x86_64, aarch64) | x86_64 |
| ansible_distribution | Operating system distribution name (e.g., Ubuntu, CentOS) | Ubuntu |
| ansible_distribution_version | Version of the OS distribution | 20.04 |
| ansible_fqdn | Fully qualified domain name of the host | web01.example.com |
| ansible_hostname | Hostname of the system | web01 |
| ansible_kernel | Kernel version of the system | 5.4.0-104-generic |
| ansible_machine | Machine hardware name (e.g., x86_64) | x86_64 |
| ansible_memtotal_mb | Total system memory in MB | 4096 |
| ansible_processor_count | Number of CPU cores | 4 |
| ansible_processor_vcpus | Number of virtual CPUs | 4 |
Example: Using Hardware Facts in a Playbook
- name: Display system memory
hosts: all
tasks:
- name: Show total memory
debug:
msg: "Total Memory: {{ ansible_memtotal_mb }} MB"
- name: Show CPU count
debug:
msg: "Number of CPUs: {{ ansible_processor_count }}"
- name: Show OS distribution
debug:
msg: "OS Distribution: {{ ansible_distribution }} {{ ansible_distribution_version }}"
Note: Hardware facts are automatically gathered by Ansible when it runs. These can be used to make decisions or tailor configurations based on the target system's hardware.
4. Using Network Facts
| Fact | Description | Example Value |
|---|---|---|
| ansible_network_os | Operating system of the network device | ios |
| ansible_network_os_family | Family of the network operating system | cisco_ios |
| ansible_net_model | Model of the network device | Catalyst 9500 |
| ansible_net_serial | Serial number of the network device | FOC21234567 |
| ansible_net_interfaces | Dictionary of network interfaces and their details | {"GigabitEthernet1/0/1": {"mtu": 1500, "speed": 1000}} |
| ansible_net_all_ipv4_addresses | List of all IPv4 addresses assigned to the device | ["192.168.1.1", "10.0.0.1"] |
Example: Gathering Network Facts
- name: Gather network facts
ansible.netcommon.network_cli:
command: show version
register: result
- name: Display network OS
debug:
msg: "OS is {{ ansible_network_os }}"
Example: Using Interface Facts
- name: Display interface information
debug:
msg: "Interface {{ item.key }} has MTU {{ item.value.mtu }}"
loop: "{{ ansible_net_interfaces | dict2items }}"
5. Using OS Facts
| Fact | Description | Example Value |
|---|---|---|
| ansible_os_family | Operating system family | RedHat |
| ansible_distribution | OS distribution name | Ubuntu |
| ansible_distribution_version | OS distribution version | 20.04 |
| ansible_kernel | Kernel version | 5.4.0-104-generic |
| ansible_machine | Machine hardware name | x86_64 |
Example: Using OS Facts in a Playbook
- name: Display OS information
hosts: all
tasks:
- name: Show OS family
debug:
msg: "OS Family is {{ ansible_os_family }}"
- name: Show distribution version
debug:
msg: "Distribution Version is {{ ansible_distribution_version }}"
6. Filtering Facts
| Filter | Description | Example |
|---|---|---|
| ansible_facts | Dictionary containing all facts gathered by Ansible | ansible_facts['ansible_hostname'] |
| ansible_all_facts | Alias for ansible_facts |
ansible_all_facts['ansible_os_family'] |
| ansible_host | Hostname or IP address of the target host | ansible_host |
| ansible_nodename | Node name of the target host | ansible_nodename |
| ansible_os_family | Operating system family (e.g., RedHat, Debian) | ansible_os_family |
| ansible_distribution | Operating system distribution name | ansible_distribution |
| ansible_distribution_version | Version of the operating system distribution | ansible_distribution_version |
| ansible_kernel | Kernel version of the target host | ansible_kernel |
| ansible_architecture | Architecture of the target host (e.g., x86_64) | ansible_architecture |
| ansible_memory_mb | Total memory in MB | ansible_memory_mb['real']['total'] |
| ansible_processor_count | Number of processors | ansible_processor_count |
| ansible_interfaces | List of network interfaces | ansible_interfaces |
| ansible_default_ipv4 | Default IPv4 address information | ansible_default_ipv4['address'] |
| ansible_mounts | Mounted filesystems | ansible_mounts |
| ansible_userspace_architecture | Architecture as reported by userspace | ansible_userspace_architecture |
| ansible_selinux | SELinux status (enabled/disabled) | ansible_selinux['status'] |
| ansible_system_capabilities | System capabilities (e.g., capabilities of the system) | ansible_system_capabilities |
| ansible_pkg_mgr | Package manager used by the system | ansible_pkg_mgr |
| ansible_service_mgr | Service manager used by the system | ansible_service_mgr |
| ansible_date_time | Date and time information | ansible_date_time['date'] |
Example: Filtering Facts by OS Family
- name: Gather facts and filter by OS family
hosts: all
gather_facts: yes
tasks:
- name: Display OS family fact
debug:
msg: "OS Family is {{ ansible_os_family }}"
- name: Conditionally execute based on OS family
command: echo "Running on RedHat-like system"
when: ansible_os_family == 'RedHat'
Example: Using Facts to Determine Memory Usage
- name: Check memory usage
hosts: all
gather_facts: yes
tasks:
- name: Display total memory in MB
debug:
msg: "Total Memory: {{ ansible_memory_mb['real']['total'] }} MB"
- name: Alert if memory less than 2GB
debug:
msg: "Warning: Low memory detected"
when: ansible_memory_mb['real']['total'] < 2048
Example: Filtering by Network Interface
- name: Get default network interface
hosts: all
gather_facts: yes
tasks:
- name: Display default IPv4 address
debug:
msg: "Default IP Address is {{ ansible_default_ipv4['address'] }}"
- name: List all network interfaces
debug:
msg: "Network Interfaces: {{ ansible_interfaces }}"
Note: Facts are gathered once per play and can be accessed in any task within that play. The
gather_facts directive must be enabled for facts to be collected.
Warning: Fact gathering can take time, especially on large inventories. Consider disabling it if you don't need the facts or are using a custom fact module.
7. Creating Custom Facts
| Property | Description | Example |
|---|---|---|
| ansible_facts | Dictionary containing all facts collected by Ansible | {"ansible_os_family": "RedHat", "ansible_hostname": "web01"} |
| custom_facts | Namespace for custom facts defined in a playbook or role | {"custom_facts": {"app_version": "2.1.0"}} |
Example: Setting a Custom Fact in a Playbook
- name: Set custom facts
set_fact:
app_version: "2.1.0"
deployment_date: "2026-04-05"
- name: Use custom facts in a task
debug:
msg: "App version is {{ app_version }}"
Example: Using Facts in Templates
- name: Create config file with custom facts
template:
src: app_config.j2
dest: /etc/app/config.json
{"version": "{{ app_version }}", "deployed_on": "{{ deployment_date }}"}
8. Caching Facts
| Option | Values | Notes |
|---|---|---|
| fact_caching | memory, redis, mongodb, jsonfile |
Backend to use for caching facts |
| fact_caching_connection | /tmp/ansible_facts, redis://localhost:6379 |
Connection string or path to cache backend |
| fact_caching_timeout | 86400 |
Timeout in seconds before cached facts expire (default 24h) |
Example: Configure Redis caching
[defaults]
fact_caching = redis
fact_caching_connection = redis://localhost:6379/0
fact_caching_timeout = 3600
Note: Caching is particularly useful in large environments where fact gathering can be expensive. Redis supports persistence and can be configured for high availability.
9. Disabling Fact Gathering
| Option | Description | Default |
|---|---|---|
| gather_facts | Controls whether Ansible collects facts about the target host | true |
Example: Disabling fact gathering for a playbook
---
- hosts: all
gather_facts: false
tasks:
- name: Print a message
debug:
msg: "No facts gathered"
Note: Disabling fact gathering can improve performance for playbooks that do not require host information.
10. Using Local Facts
| Property | Description | Example |
|---|---|---|
| ansible_local | Namespace for local facts in Ansible | {"ansible_local": {"myapp": {"version": "1.0", "status": "running"}}} |
Example: Setting Local Facts
- name: Set local facts
set_fact:
ansible_local:
myapp:
version: "1.0"
status: "running"
Example: Reading Local Facts
- name: Display local facts
debug:
msg: "App version is {{ ansible_local.myapp.version }}"
Note: Local facts are stored in
/etc/ansible/facts.d/ on the managed node and are gathered at inventory time.
Warning: Local facts are not automatically refreshed and require a manual refresh or reboot to update.
11. Refreshing Facts Mid-Playbook
| Option | Values | Notes |
|---|---|---|
| ansible_facts | refresh |
Refresh facts during playbook execution |
| delegate_to | localhost |
Run fact gathering on localhost |