Filter, lookup, module or action plugin · Ansible

Ansible has around twenty plugin types. Four of them get written by users, and choosing between them looks like a taxonomy problem.

It is not. It is one question:

Does this code need to run on the controller, or on the managed node?

Answer that and the type follows. Get it wrong and you produce automation that works perfectly on the developer’s laptop, works perfectly in a play targeting localhost, and reads the wrong machine in production — while reporting success.

The four types, by where they execute

Type	Runs on	Sees	Can change the target
Filter	Controller	Data you passed it	No
Lookup	Controller	The controller’s filesystem, environment, network	No
Module	Managed node	The managed node’s filesystem, processes, services	Yes
Action plugin	Controller, and usually dispatches a module to the node	Both, deliberately	Yes, via the module it dispatches

The first two are transformations and reads. The third is the only one that acts on the host. The fourth is the seam between them, and it is the one you almost never need.

The demonstration

A play targeting two remote hosts, with a lookup reading a file.

Read-only / Safelookupdemo.yml— READ-ONLY: debug prints and nothing else. Note the play targets two hosts in the documentation range 192.0.2.0/24, which is unreachable by design.

- name: A lookup in a play targeting remote hosts
hosts: web01.example.com,web02.example.com
gather_facts: false
tasks:
  - name: Read a file with a lookup
    ansible.builtin.debug:
      msg: "{{ lookup('file', playbook_dir + '/marker.txt') }}"

Read-only / Safethe result against two unreachable hosts— Real output from ansible-core 2.21.3. Both hosts are in 192.0.2.0/24 and were never contacted. The file contents printed are the controller's, and the recap reports two successful hosts.

$ ansible-playbook -i inventory/hosts.yml lookupdemo.yml

TASK [Read a file with a lookup] ***********************************************
ok: [web01.example.com] => {
  "msg": "controller-copy"
}
ok: [web02.example.com] => {
  "msg": "controller-copy"
}

PLAY RECAP *********************************************************************
web01.example.com          : ok=1    changed=0    unreachable=0    failed=0
web02.example.com          : ok=1    changed=0    unreachable=0    failed=0

Read that recap carefully. Two hosts that do not exist, that no packet ever reached, both reported ok=1 and unreachable=0. The lookup ran twice on the controller — once per host in the play — and read the controller’s file both times.

This is the failure signature to recognise

A play that reads /etc/something from what its author believed was the managed node, using a lookup, has three properties that make it hard to catch:

It works in development. The developer’s controller is the target during testing, so the file is the right file and the result is correct.

It produces plausible values. The controller is a Linux host with /etc/os-release, /etc/resolv.conf and a hostname, so the lookup returns something that looks like an answer.

It reports success on hosts it never touched. As above. Nothing in the recap, at any verbosity, distinguishes a lookup that ran on the controller from a module that ran on the node.

The consequence is a template rendered from the controller’s configuration and pushed to three hundred machines, or a conditional that gates a change on the controller’s state. Both have happened.

The correct form, when the file is genuinely on the managed node:

Read-only / Safereading a remote file with a module— READ-ONLY: slurp reads a file and returns its contents base64-encoded; stat reads metadata. Both execute on the managed node.

- name: Read the file from the managed node
ansible.builtin.slurp:
  src: /etc/app/version
register: remote_version

- name: Use it
ansible.builtin.debug:
  msg: "{{ remote_version['content'] | b64decode | trim }}"

# Or, when you only need to know whether it exists:
- name: Check for the marker
ansible.builtin.stat:
  path: /etc/app/version
register: marker

slurp returns base64 because the file may contain anything, including bytes that are not valid text. The | b64decode is not ceremony; it is the price of a module that can read any file.

Choosing, in order of cost

Work down. Stop at the first that fits.

Is it a pure transformation of data you already have? A filter. Cheapest by a wide margin: a plain Python function, no state, no idempotency, no changed value, no check mode.
Does it read something on the controller - a file, an environment variable, a secret manager, an API the controller can reach? A lookup. Still controller-side, still no change semantics.
Does it need to inspect or modify the managed node? A module. Now you owe the full contract from lesson 3.
Does it need to do controller-side work AND dispatch a module - copy a file into place before running something, or template on the controller then transfer? An action plugin. Read the built-in ones first; template and copy are action plugins and they are how you learn the pattern.
If two answers seem to fit, prefer the one further up this list. The cost difference between a filter and a module is not small.

Two cases that look ambiguous and are not

“It calls an API, so where does it run?” Whichever side has the network route and the credentials. Most APIs are reachable from the controller, so uri or a lookup is correct and no managed node is involved at all — which is why so many cloud modules are effectively controller-side work with delegate_to: localhost. If the API is only reachable from the managed node, it must be a module.

“It reads a file, so it must be a lookup.” Only if the file is on the controller. This is the confusion the demonstration above exists to break, and the discriminating question is never “what does the code do” but “which machine’s disk holds the bytes”.

Under the hood

Why can a lookup not run on the managed node, given that a module can?

Because of when it is evaluated. Lookups are part of the templating layer. {{ lookup('file', ...) }} is resolved by Jinja while ansible-core is building the task’s parameters — before any connection is used, before the module payload is assembled, before anything is sent anywhere. There is no target-side context in existence at that moment, so there is nowhere else it could run.

That is also why lookups appear inside vars:, when:, task arguments and inventory files: templating happens everywhere, and lookups go wherever templating goes. And it is why a lookup evaluates once per host in the play — the templating is per host, because the variables are per host — which is what produced two identical results in the demonstration.

Action plugins sit at the other end of the same pipeline. When a task runs, ansible-core looks for an action plugin matching the module name and, if it finds one, runs that on the controller instead of shipping the module directly. The action plugin then does controller-side work and may call self._execute_module(...) to dispatch a module to the node.

This is not an exotic mechanism — it is how the modules you use every day work. template is an action plugin: it renders the template on the controller, where the variables and the Jinja environment live, then transfers the result and calls the copy module on the node. copy, fetch, assemble, unarchive and script are all action plugins for similar reasons. Understanding this explains an otherwise puzzling fact: template needs no Jinja on the managed node, because no templating happens there.

The practical rule that follows: if you find yourself wanting a module that can also see controller-side state, you want an action plugin, and you should read template’s implementation before writing one. If you find yourself wanting a lookup that can see the managed node, you want a module, and no amount of plugin cleverness will change where templating happens.

What happens if you need the same logic on both sides?

It happens more than the taxonomy suggests: parsing a vendor configuration format, for instance, might be needed both to read a remote file and to validate a local one.

Put the logic in one place and call it from two. For a collection, that place is plugins/module_utils/. A module imports it directly and the code travels in the AnsiballZ payload; a filter or lookup running on the controller can import it too, because module_utils is importable on both sides — it is shipped to the node and available locally.

Do not duplicate it. Two copies of a parser diverge, and they diverge in the direction that is hardest to notice: the controller-side copy gets fixed because that is where people debug, and the target-side copy quietly keeps the bug.

Question whether both sides genuinely need it. Frequently one side can be eliminated. If the parser exists so the controller can understand a file that lives on the managed node, slurp the file and parse it once on the controller with a filter — no module needed, no fleet-wide Python dependency, and the parsing is testable without any host at all.

That last move is worth reaching for. Reading remote data with a module and processing it with a controller-side filter is often the cleanest shape available, and it keeps the expensive contract confined to the part that genuinely must run remotely.

Knowledge check

Why this matters

Every other decision in this part is about cost. This one is about correctness, and it is the only defect in Part LI that produces a play which is confidently, silently wrong.

A module with a bad changed value produces restart storms — annoying, and traceable once somebody looks. A lookup used where a module was needed produces a run that reports ok on three hundred hosts it never contacted, having read one machine’s disk and used the answer everywhere. There is no recap line, no verbosity level and no lint rule that distinguishes it from correct behaviour.

The protection is the question, asked before any code is written: which machine holds the thing this code needs to see? Filters and lookups run where the playbook is parsed. Modules run where the change happens. Action plugins straddle the seam, and the built-in ones — template, copy, fetch — are the reason your everyday plays work the way they do.

Asked at design time it takes ten seconds. Asked in production it is an incident review.