A Comprehensive Guide to Ansible Fact Caching Configuration

Ansible fact caching helps when your playbooks spend too much time gathering the same host facts on every run. If you manage hundreds of hosts, repeated setup module calls can add noticeable SSH overhead before the real work even starts.

Fact caching stores gathered facts after a successful run, then reuses them while the cache is still valid. The result is faster playbook startup for workflows that can tolerate facts being slightly stale.

Understanding Ansible Facts and Performance Impact

Ansible gathers facts with the setup module, either explicitly or through the default gather_facts: true behavior. Facts include details such as OS family, kernel, IP addresses, mounts, CPU, memory, and Python interpreter information.

The performance gain comes from avoiding repeated remote collection when cached data is fresh. That is useful for reporting, templating, and conditional logic that depends on facts which do not change minute to minute.

Configuration Methods for Fact Caching

Ansible configures fact caching in ansible.cfg. Two practical choices are local JSON files and Redis. The exact plugin names matter.

1. JSON File Caching (Local Storage)

The JSON file cache stores facts on the control machine. It is simple and needs no external service.

Configuring JSON Caching in ansible.cfg

Use the jsonfile cache plugin:

[defaults]
fact_caching = jsonfile
fact_caching_connection = /path/to/ansible_facts_cache
fact_caching_timeout = 600

fact_caching_connection is the directory where Ansible writes cache files. Create it first and make sure the user running Ansible can write to it:

mkdir -p /path/to/ansible_facts_cache

fact_caching_timeout is measured in seconds. After the timeout, Ansible gathers fresh facts again when a play needs them.

2. Redis Caching (Shared, High-Performance Storage)

Redis works better when multiple control nodes, users, or CI jobs should share the same fact cache.

Prerequisites for Redis Caching

You need a reachable Redis server and the Python Redis client available in the Python environment Ansible uses:

python -m pip install redis

Configuring Redis Caching in ansible.cfg

Use a Redis connection string:

[defaults]
fact_caching = redis
fact_caching_connection = 127.0.0.1:6379/0
fact_caching_timeout = 3600

The /0 selects Redis database 0. Use a dedicated database or Redis instance if other applications also use Redis, and protect the Redis endpoint like any other infrastructure service.

Integrating Caching into Playbooks

The cache is populated when a play gathers facts:

- name: Gather and use facts
  hosts: webservers
  gather_facts: true
  tasks:
    - name: Show OS family
      debug:
        msg: "OS Family is {{ ansible_os_family }}"

With fact caching enabled, Ansible can reuse cached facts while they are valid. If facts are missing or expired and gather_facts: true, Ansible gathers them again.

If you set gather_facts: false, Ansible does not run fact gathering for that play. Cached facts may still be available through host variables if they were already cached, but do not rely on that blindly for critical logic. A missing cache can make variables undefined.

A safe pattern is to gather facts in a scheduled or early play, then use cached facts in later reporting or orchestration playbooks where staleness is acceptable.

Managing the Fact Cache

Clear the cache when host facts changed and you do not want to wait for the timeout.

Clearing JSON Cache

Delete the files in the configured cache directory:

rm -rf /path/to/ansible_facts_cache/*

Clearing Redis Cache

If the Redis database is dedicated to Ansible facts, you can flush that database:

redis-cli -n 0 FLUSHDB

FLUSHDB deletes every key in the selected Redis database. Do not run it on a shared database unless you know every key there is safe to delete.

Best Practices

• Use jsonfile for a single control machine and simple local workflows.
• Use Redis when multiple runners need the same cache.
• Keep timeouts short for fast-changing infrastructure and longer for stable fleets.
• Do not cache sensitive custom facts in a location other users can read.
• Verify which config file Ansible is using with ansible --version.
• Test with one inventory group before enabling caching across a large fleet.

Practical Takeaway

Enable Ansible fact caching when repeated fact gathering is a measurable cost and your playbooks can tolerate cached data. Start with jsonfile, move to Redis only when sharing the cache solves a real workflow problem, and set a timeout that matches how often your host facts change.