Skip to main content

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
{
  "address": "192.168.1.10",
  "netmask": "255.255.255.0"
}

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

Example: Refreshing Facts Mid-Playbook

- name: Refresh facts mid-playbook
  hosts: all
  tasks:
    - name: Gather facts again
      setup:
        refresh: true
      delegate_to: localhost

Was this article helpful?