Skip to content
DevOps AI ToolKit
Newsletter
All prompts
AI for Ansible Difficulty: Advanced ClaudeChatGPTCursor

Ansible Custom Lookup Plugin Authoring Prompt

Draft a lookup plugin that pulls values from an external source at template time with correct terms/variables handling, error behavior, and caching.

Target user
Engineers who need to read secrets or config from a bespoke backend inside playbooks without shelling out
Difficulty
Advanced
Tools
Claude, ChatGPT, Cursor

The prompt

You are a senior Ansible engineer who writes a lookup plugin when a value must come from an external system at template time, because a lookup is the supported, controller-side seam for reading data — not a `command` shelling out to a CLI and parsing stdout.

I will describe an external source I need to read from inside plays. Draft a lookup plugin that does it correctly.

Steps:

1. **LookupModule structure**: subclass `LookupBase`, implement `run(self, terms, variables=None, **kwargs)`, and return a list (lookups always return a list).
2. **Terms and options**: parse `terms` for the keys/paths requested, and declare typed options in a `DOCUMENTATION` block read via `set_options`/`get_option` (endpoint, auth, mount).
3. **Controller-side awareness**: make clear the lookup runs on the controller, so credentials and network reachability are the controller's, not the managed node's.
4. **Error behavior**: raise `AnsibleError` with a clear message on auth/timeout/not-found rather than returning an empty list that silently becomes an empty variable.
5. **Caching / rate limits**: if the backend is slow or rate-limited, cache within the run and document the tradeoff.
6. **Secret hygiene**: instruct callers to wrap sensitive results with `no_log: true` and never persist the value.

Fill in:
- Backend and how it is queried: [DESCRIBE]
- Auth method: [token / approle / kubeconfig]
- Term format callers will pass: [e.g. "secret/data/app#password"]

Output format: the lookup plugin Python with a documented options block, a usage snippet showing `lookup('ns.coll.name', ...)` and the `with_`/loop form, error-path behavior, and a note on no_log.

Run this prompt with AI

Test it, get an AI-improved version, or compare models — live in the Prompt Workspace. No copy-paste.

Why this prompt works

Reaching for a lookup plugin instead of a command task that greps a CLI is the difference between supported, testable data access and a brittle stdout-parsing hack. This prompt makes the controller-side nature of lookups explicit, which is the detail that trips people up: the credentials and network path belong to the machine running Ansible, not the target host, and confusing the two is a common source of “works locally, fails in CI” bugs.

The error-behavior rule is the load-bearing one. A lookup that swallows a backend failure and returns an empty list doesn’t fail — it silently feeds an empty string into every consuming task, which is far harder to debug than a clean stop. By mandating AnsibleError on failure and no_log on sensitive returns, the prompt keeps a data-access plugin from becoming either a silent-corruption or a secret-leak vector.

Related prompts

More Ansible prompts & error guides

Browse every Ansible prompt and troubleshooting guide in one place.

Free download · 368-page PDF

Reading prompts? Get all 500 in one free PDF

500 battle-tested, copy-paste AI prompts engineered by a senior systems engineer — every one with fill-in placeholders and safety/back-out notes. Drop your email and it's yours.

  • 500 prompts: Linux · Kubernetes · Terraform · OpenStack · GitLab · Docker · Monitoring · Incident Response
  • Instant PDF download — yours free, forever
  • Plus one practical AI-workflow email a week (no spam)

Single opt-in · unsubscribe anytime · no spam.