In Ansible, there are three types of Special Variables.

• Connection Variables
• Magic Variables
• Facts (this article)

Facts are raw data about a system. On your control node (that's your Ansible server), the following command will display facts about your control node.

ansible localhost -m setup

Or, let's say you have a couple Amazon Web Services (AWS) EC2 instances defined in your default hosts file or your own inventory file, .

aws:
  hosts:
    ec2-3-82-233-47.compute-1.amazonaws.com:
    ec2-23-22-195-223.compute-1.amazonaws.com:

Here is how you could display facts for each AWS EC2 instance.

ansible aws -m setup

For example, here are some facts.

"ansible_hostname": "server1"
"ansible_all_ip4v_addresses": "10.1.2.3"
"ansible_distribution": "CentOS"

Often, there are to many facts to display on screen. You can use grep find a certain fact.

ansible localhost -m setup | grep -i ansible_distribution

Or redirect the output to a file.

ansible localhost -m setup > facts.txt

gather_facts plugin

By default, a playbook will gather facts. Here is a playbook that prints facts.

---
- hosts: all
  tasks:
  - debug:
      var: ansible_hostname
  - debug:
      var: ansible_all_ipv4_addresses
  - debug:
      var: ansible_distribution

Since facts are gathered by default, there is no need to use the gather_facts plugin. However, you can include the gather_facts parameter if you would like, as this could emphasize that facts are indeed being gathered. The gather facts parameter is a wrapper that actually invokes the setup module. 

The ansible-doc gather_facts command can be used to show the Ansible documention on the gather_facts parameter.

---
- hosts: all
  gather_facts: true
  tasks:
  - debug:
      var: ansible_hostname
  - debug:
      var: ansible_all_ipv4_addresses
  - debug:
      var: ansible_distribution

Running the playbook will produce the following.

PLAY [all]

TASK [Gathering Facts]
ok: [server1.example.com]

TASK [debug]
ok: [server1.example.com] => {
    "msg": "server1"
}

TASK [debug]
ok: [server1.example.com] => {
    "msg": "10.1.2.3"
}

TASK [debug]
ok: [server1.example.com] => {
    "msg": "CentOS"
}

PLAY RECAP
server1.example.com : ok=2  changed=0  unreacable=0  failed=0

If you do not need to use facts, the gather_facts module can be set to "no" or "false" to not gather facts.

---
- hosts: all
  gather_facts: false

when parameter

Facts are often used with when to do something when a fact evaluates to true or false. In this example, Nginx will be installed if the distribution is CentOS.

---
- hosts: localhost
  tasks:
  - name: Install Nginx
    package:
      name: nginx
      state: latest
    when: ansible_distribution == 'CentOS'
...

Sometimes, certain facts may not exist. For example, let's say the system contains the /dev/sda device but does not contain a /dev/sdb device. In this example, the ansible_devices.sda fact will exist, but the ansible_devices.sdb fact will not exist. This could be a situation where the when statement could come in handy.

---
- hosts: all
  tasks:
    - name: add /var entry to /etc/fstab
      mount:
        path: /var
        src: UUID="{{ ansible_devices.sda.partitions.sda1.uuid }}"
        fstype: ext4
        opts: defaults
        dump: '1'
        state: present
    when: ansible_devices.sda.partitions.sda1 is defined
...