Ansible facts are variables automatically discovered by Ansible on a managed host. Facts contain host-specific information that can be used just like regular variables in plays, conditionals, loops, or any other statement that depends on a value.

By default, each play in a playbook automatically runs the setup module before its first task to gather facts from each managed host that matches the play’s host pattern.

Running the setup module to collect facts for every play has performance consequences, especially on a large set of managed hosts. If you are not using any facts in the play, you can speed up execution by turning off automatic fact gathering by setting gather_facts: no in the play.

However, you might need to use facts in your play. You can configure fact caching in automation controller to store facts collected by one job so that they can be used by a later job. One playbook can collect facts for all hosts in the inventory and cache those facts so that later playbooks can use them without fact gathering or manually running the setup module.

Fact caching is also useful if you use the "magic" variable hostvars to write a play in which a task running on one host references facts that belong to another host. For example, a task running on the managed host servera can access the value of the ansible_facts['default_ipv4']['address'] fact for serverb by referencing the hostvars['serverb']['ansible_facts']['default_ipv4']['address'] variable. If you are not using fact caching, then referencing the hostvars['serverb']['ansible_facts']['default_ipv4']['address'] variable only works if facts have already been gathered from serverb by this play or by an earlier play in the same playbook.

Retaining cached facts ensures that the play has current data but can also have some negative consequences. One possible consequence is that the fact values become outdated. For example, a fact might contain a list of the software packages installed on the system. If the fact cache is not updated after a software update, that fact might contain inaccurate data. You must therefore periodically refresh your cached facts.

Enabling Fact Caching in Automation Controller

Automation controller includes integrated support for fact caching and a database for storing the fact cache. You need to manage time-outs for the fact cache at a global level. Fact caching control is determined by the job template.

Automation controller uses a global setting to control when facts expire. When configured, facts for each host are only considered valid for the defined number of seconds since the last time the facts were refreshed. Navigate to Settings and then click the Job Settings link. The value of Per-Host Ansible Fact Cache Timeout specifies how long in seconds cached Ansible facts are considered valid after they have been collected. When the facts in the cache become invalid, you need to collect them again before you can reference them. To edit the field, click Edit at the bottom of the page, enter a new value for the Per-Host Ansible Fact Cache Timeout field, and click Save.

Figure 5.1: Setting the per-host Ansible fact cache time-out

To optimize fact caching, set gather_facts: no in the playbook file to disable automatic fact gathering in the play.

To use cached facts:

1. A play must gather facts and the job template that runs the associated playbook must enable fact storage.

2. If a different playbook requires cached facts, then the job template that runs the associated playbook must also enable fact storage.

One way to do this in automation controller is to set up a playbook that gathers facts as a scheduled job. That job could run a normal playbook that gathers facts, or you could set up a minimal playbook to gather facts, such as the following example:

- name: Refresh fact cache
  hosts: all
  gather_facts: true

Because the play does not include a tasks or a roles section, this play only gathers facts.

Note

You do not need to gather facts for all your hosts at the same time. It might make sense to gather facts for smaller sets of hosts to spread the load. What matters is that you gather facts for all of your hosts before they expire or become stale.

The following procedure shows how to enable fact caching in the automation controller interface:

1. Navigate to Resources → Templates.

2. For the appropriate job template, click the Edit Template icon and then scroll to the bottom of the page and click Edit to edit the settings.

3. In the Edit Details section, scroll to the bottom and select Enable Fact Storage.

   Figure 5.2: Enabling fact storage

4. Click SAVE to save the modified job template configuration.

Whenever you run a new job based on a template that has the Enable Fact Storage option set, that job uses the fact cache. If the Ansible Playbook also has the gather_facts variable set to yes or calls the setup module as a task, the job also gathers facts and stores them in the fact cache.

Important

If a job gathers some facts but not others, the facts that have been newly gathered are updated in the fact cache.

When you launch a job, automation controller injects all Ansible facts for each of the managed hosts from the running job into a memory cache. After finishing the job, automation controller retrieves all the records for a particular host from this cache, and then saves each fact that has an update time later than the cached copy in the fact cache database.

References

Ansible User Guide: Caching Facts

Automation Controller User Guide: Fact Caching