Ansible Custom Vars Plugin Authoring Prompt
Draft a custom Ansible vars plugin that injects variables from an external source at the right precedence, with caching and clear failure behavior.
- Target user
- Engineers who need group/host vars from a CMDB, secrets store, or external API instead of static YAML
- Difficulty
- Advanced
- Tools
- Claude, ChatGPT, Cursor
The prompt
You are a senior Ansible engineer who writes vars plugins sparingly and carefully. You know a vars plugin runs for every inventory source and host, injects variables at a defined precedence, and can wreck performance or leak secrets if written naively.
I will describe an external source of host/group variables. Draft a custom vars plugin (`BaseVarsPlugin` subclass) that loads them safely.
Steps:
1. **Scope and precedence**: state exactly where vars-plugin output sits in Ansible variable precedence, and confirm the variables you inject won't unexpectedly override inventory or play vars the user set on purpose.
2. **get_vars implementation**: write `get_vars(self, loader, path, entities)` returning a dict, handling both host and group entities, and degrading gracefully (return `{}`, not an exception) when the source is unreachable.
3. **Activation controls**: implement `REQUIRES_ENABLED` / `REQUIRES_WHITELIST` and the `stage` option (`inventory` vs `task`) so the plugin only runs when explicitly enabled, and document the `ansible.cfg` to enable it.
4. **Caching**: cache lookups per run so the same external call isn't made once per host; show how to key and invalidate the cache.
5. **Secret hygiene**: if the source returns credentials, ensure they are not logged and recommend marking downstream usage `no_log`.
6. **Failure modes**: define behavior on timeout, auth failure, and partial data — fail loudly only when the data is required, otherwise warn and continue.
Fill in:
- External source and how it's queried: [e.g. internal CMDB REST API, Vault path, CSV]
- Which entities map to which vars: [DESCRIBE]
- Is any returned data secret: [yes/no + which fields]
- Should missing data be fatal or a warning: [fatal / warn]
Output format: the plugin Python with a documented `DOCUMENTATION` block, the `ansible.cfg`/enablement snippet, a precedence note, and a test plan (one host, `ansible-inventory --graph --vars`) to verify injected values before relying on them.
Do not run this against production inventory. Recommend a throwaway inventory with one host and a read-only credential first; a vars plugin that errors can break every play that loads that inventory.
Why this prompt works
A vars plugin is the most powerful and the most dangerous extension point in the inventory layer, because it runs implicitly for every host on every inventory load. That is exactly why most teams should reach for it rarely and write it carefully when they do. This prompt front-loads the two questions that determine whether the plugin helps or hurts: where its output sits in variable precedence, and how it behaves when the external source is slow or down. Get precedence wrong and the plugin silently overrides values operators set on purpose; get failure handling wrong and one unreachable API stalls every playbook in the organization.
The implementation steps map directly to the real BaseVarsPlugin contract — a get_vars that handles host and group entities, REQUIRES_ENABLED so the plugin never activates by accident, and the stage option that controls whether it runs at inventory time or task time. Spelling these out keeps the AI from producing a plausible-looking plugin that quietly ignores the activation controls and runs everywhere. The caching step is not a nicety either: without per-run caching, a naive plugin makes the same external call once per host and turns a hundred-host inventory into a hundred API requests.
The guardrails treat the plugin as inventory-layer infrastructure rather than a task. Because an exception in get_vars can break every play that loads the inventory, the prompt insists on graceful degradation and a throwaway one-host inventory for the first test. And because these plugins often exist precisely to pull credentials from a store, it keeps secret hygiene — no logging, downstream no_log — in scope from the start rather than as an afterthought.