Cache and vars plugins

Two related but smaller plugin types. Cache plugins persist arbitrary data (most importantly, gathered facts and inventory query results) between runs. Vars plugins are sources of variables consulted by the variable manager — host_group_vars is the only one shipped in core, but collections add more.

Cache plugins

lib/ansible/plugins/cache/:

__init__.py     # BaseCacheModule
memory.py       # In-process dict; lasts only while the controller is running
jsonfile.py     # JSON files in a directory; persists across runs

Collections add more: community.general ships redis, mongodb, memcached, pickle, yaml. They all conform to the same key-value contract.

BaseCacheModule

lib/ansible/plugins/cache/__init__.py:BaseCacheModule is the abstract base:

Method	Purpose
get(key)	Retrieve a value; raise KeyError on miss
set(key, value)	Store a value
keys()	List all stored keys
contains(key)	Predicate
delete(key)	Remove
flush()	Empty the cache
copy()	Snapshot of current state

For a cache that needs to expire entries, the base also handles _timeout checks (caches read timeout from the plugin's options).

memory

lib/ansible/plugins/cache/memory.py is a 30-line dict wrapper. Useful for in-process caching during one controller run. The default for fact caching when no cache plugin is explicitly configured.

jsonfile

lib/ansible/plugins/cache/jsonfile.py writes one JSON file per key into the configured directory. Persists across runs so subsequent invocations of the same playbook can skip gather_facts and use cached fact data.

Configure with:

[defaults]
fact_caching = jsonfile
fact_caching_connection = ~/.ansible/facts_cache
fact_caching_timeout = 86400

What gets cached

Cache plugins are used in two distinct contexts:

• Fact cache — setup results, addressed by (host, fact_subset). Read by VariableManager when constructing per-host vars; written by the gather_facts action plugin.
• Inventory cache — cloud inventory plugin output, addressed by plugin name + path. Read/written by the inventory plugin itself in parse(cache=True).

The same plugin can serve both. The cache_plugin option for an inventory plugin and the fact_caching option are independent and can use different backends.

Vars plugins

lib/ansible/plugins/vars/:

__init__.py        # BaseVarsPlugin
host_group_vars.py # Reads host_vars/ and group_vars/ directories

Vars plugins are how the variable manager finds extra variable sources beyond the inventory and the play. The only built-in is host_group_vars, which handles the conventional host_vars/<host>.yml and group_vars/<group>.yml files.

Vars plugins run with one of three triggers (stage:):

• inventory — when inventory is loaded.
• task — when a task is about to run.
• all — both.

The default is inventory, which is what host_group_vars uses.

BaseVarsPlugin

lib/ansible/plugins/vars/__init__.py:BaseVarsPlugin defines:

Method	Purpose
get_vars(loader, path, entities, cache=True)	Return a dict of vars for the given inventory entities (hosts/groups) at the given path

entities is a list of Host and Group objects; the plugin returns a dict that the variable manager merges in.

host_group_vars walks the filesystem

For each inventory source, host_group_vars looks for host_vars/ and group_vars/ subdirectories adjacent to it. It supports:

• Single files: host_vars/web01.yml, group_vars/all.yml.
• Directories of files: host_vars/web01/, group_vars/webservers/{main.yml,secrets.yml} — all files merged.
• YAML, JSON, and Vault-encrypted variants.

Files matching the INVENTORY_IGNORE_PATTERNS and INVENTORY_IGNORE_EXTS lists are skipped (defaults exclude .swp, .pyc, etc.).

Vars precedence

host_group_vars is one of 22 var sources that lib/ansible/vars/manager.py:VariableManager.get_vars merges together. The exact order is documented in the docstring of get_vars and in the official Ansible docs. The summary:

1. Role defaults (defaults/main.yml) — lowest.
2. Inventory file vars.
3. Inventory host_vars/ and group_vars/ (via host_group_vars).
4. Playbook host_vars/ and group_vars/ (also via host_group_vars, applied to the playbook directory).
5. Playbook vars:.
6. Role vars/main.yml.
7. Block vars.
8. Task vars.
9. set_fact (registered).
10. register:.
11. Extra vars (-e) — highest.

Adding a vars plugin that runs at task stage is one way to splice in something more dynamic.

Integration points

• Cache plugins:
  • Loaded by: cache_loader.
  • Used by: lib/ansible/vars/manager.py (fact cache), lib/ansible/plugins/inventory/__init__.py (inventory cache), and any plugin that opts into caching via the inventory_cache doc fragment.
• Vars plugins:
  • Loaded by: vars_loader.
  • Used by: lib/ansible/vars/plugins.py:get_vars_from_inventory_sources and get_vars_from_path, called from VariableManager.get_vars.

Entry points for modification

• A new cache backend — write a plugin in a collection. Subclass BaseCacheModule. Implement the seven abstract methods. Declare connection/timeout options in DOCUMENTATION.
• A new vars source — subclass BaseVarsPlugin. Be aware of staging semantics: task-stage plugins run before every task, which can be expensive.
• Changing variable precedence — lib/ansible/vars/manager.py:VariableManager.get_vars. Don't do this without strong consensus; users have built years of playbooks around the current order.

Cross-links

• Fact gathering — the main consumer of fact caches.
• Dynamic inventory — the main consumer of inventory caches.
• Primitives → Host and inventory — what the vars plugins enrich.