Overview Ansible can cache facts from hosts when running playbooks. Instead of gathering facts during each ansible-cmdb run, you can use these pre-cached facts for faster CMDB generation.
Ansible Fact Cache Configuration First, configure Ansible to cache facts. In your ansible.cfg:
[defaults] fact_caching =jsonfile fact_caching_connection =/path/to/facts/dir
Store facts as JSON files on disk: [defaults] fact_caching =jsonfile fact_caching_connection =/var/cache/ansible/facts
Store facts in Redis (requires redis Python package): [defaults] fact_caching =redis fact_caching_connection =localhost:6379:0
Ansible-cmdb only supports reading from jsonfile fact caches, not Redis or other backends.
Using Fact Cache with ansible-cmdb Use the -f or --fact-cache option to indicate that the directory contains fact-cache files:
ansible-cmdb -f /path/to/facts/dir > overview.html
Complete Example [defaults] fact_caching =jsonfile fact_caching_connection =/var/cache/ansible/facts fact_caching_timeout =86400
Fact Cache vs Regular Facts Understanding the difference between fact cache files and regular setup output:
Generated by ansible -m setup --tree out/ all: File structure: { "ansible_facts" : { "ansible_hostname" : "web1" , "ansible_os_family" : "Debian" , ... } }
Usage: ansible-cmdb out/ > overview.html
Generated by Ansible playbook runs with fact caching enabled: File structure: { "ansible_hostname" : "web1" , "ansible_os_family" : "Debian" , ... }
Note: No ansible_facts wrapper key. Usage: ansible-cmdb -f /var/cache/ansible/facts > overview.html
The --fact-cache option applies to all fact directories you specify. You cannot mix fact-cache directories and regular setup directories in the same command. # This will NOT work correctly: ansible-cmdb -f /cache/facts /regular/facts > overview.html
Extending Fact Cache Data When using --fact-cache, the JSON structure is different for manually extended facts.
With Fact Cache Omit the ansible_facts key and put items in the root:
{ "ansible_userspace_architecture" : "x86_64" , "ansible_distribution" : "Ubuntu" }
Without Fact Cache Include the ansible_facts key:
{ "ansible_facts" : { "ansible_userspace_architecture" : "x86_64" , "ansible_distribution" : "Ubuntu" } }
When using --fact-cache, you can only extend native Ansible facts, not information read from the inventory file by ansible-cmdb (like groups or host variables).
Example: Extending Fact Cache Create a directory for extended facts:
mkdir /var/cache/ansible/facts_extend
Add missing information for a host:
File: /var/cache/ansible/facts_extend/openbsd.dev.local { "ansible_userspace_architecture" : "x86_64" , "ansible_python_version" : "3.9.0" }
Generate CMDB with both directories:
ansible-cmdb -f /var/cache/ansible/facts /var/cache/ansible/facts_extend > overview.html
Benefits of Fact Caching Cache Freshness Control how long Ansible caches facts:
[defaults] fact_caching =jsonfile fact_caching_connection =/var/cache/ansible/facts fact_caching_timeout =86400 # 24 hours in seconds
Set fact_caching_timeout based on how frequently your infrastructure changes:
Dynamic environments: 3600 (1 hour)
Stable environments: 86400 (24 hours)
Very stable: 604800 (1 week)
Combining with Inventory You can use fact caching with inventory scanning:
ansible-cmdb -f -i ./hosts /var/cache/ansible/facts > overview.html
This combines:
Cached Ansible facts from /var/cache/ansible/facts
Group and host variables from the inventory
Workflow Example Here’s a complete workflow using fact caching:
1. Configure Ansible
2. Run Playbooks
3. Generate CMDB
4. Automate (Cron)
# ansible.cfg [defaults] fact_caching =jsonfile fact_caching_connection =/var/cache/ansible/facts fact_caching_timeout =86400 gathering =smart
Troubleshooting Facts not found Verify the cache directory exists and contains fact files:
ls -la /var/cache/ansible/facts/ # Should show files named after your hosts
Wrong fact structure Fact cache files should NOT have the ansible_facts wrapper:
# Check a fact file cat /var/cache/ansible/facts/hostname | head -n 5 # Should start with fields like "ansible_hostname", not "ansible_facts"
Mixed cache and regular facts Remember: you cannot mix fact types in one command.
# Wrong - mixing types ansible-cmdb -f /cache/facts /setup/output > overview.html # Right - all fact cache ansible-cmdb -f /cache/facts /cache/facts_extend > overview.html # Right - all regular facts ansible-cmdb /setup/output /setup/extend > overview.html
Stale facts If facts seem outdated:
Check fact_caching_timeout in ansible.cfg
Manually clear the cache:
rm -rf /var/cache/ansible/facts/ *
Run a playbook to repopulate:
ansible-playbook -i hosts site.yml
Best Practices
Use with automation - Fact caching is ideal for automated CMDB generationSet appropriate timeouts - Balance freshness vs. performanceMonitor cache size - Old hosts may accumulate; clean periodicallyDocument the structure - Team members should know you’re using fact cacheBackup cache files - Include in your backup strategy if using as source of truth