Custom Plugins

Plugins extend Ansible on the control node, not on the target. They run inside the Ansible process before or during a play, where a module runs out on the managed host. That single difference in where the code executes is the thing to hold onto: a plugin sees the control node's filesystem, credentials, and network position, because that is where it lives.

Three plugin types cover almost everything you would write. A filter plugin transforms data inside a Jinja2 expression, a lookup plugin pulls external data into a variable, and a callback plugin reacts to play events — most often for custom logging or output. All three are short Python files that Ansible discovers from a typed plugin directory, and the type you pick is dictated by when in a play you need to act.

The Plugin-vs-Module Line

Modules are shipped to the node and executed there with the task's privileges. Plugins execute in the control process, with the control node's credentials and environment. That is the whole reason a lookup('file', ...) reads a file on your laptop and not on web1.larkspur.io: the lookup ran on the controller, where the play is orchestrated, never on the host the play targets. If you ever forget which is which, ask where the work has to happen — on the remote machine, or in Ansible's own process.

Filter Plugins

A filter plugin is a Python function registered in a FilterModule class, callable in Jinja2 like any built-in filter: {{ backends | larkspur.web.to_haproxy_backend }}. You write one when the built-in filters plus community.general cannot express the transform you need — a domain-specific reshaping of data that would otherwise be an unreadable pile of nested Jinja2. It lives in filter_plugins/ next to a playbook, or in a collection's plugins/filter/.

# a FilterModule exposes named functions to Jinja2
def to_haproxy_backend(hosts, port=8080):
    return [
        f"server {h['name']} {h['ip']}:{port} check"
        for h in hosts
    ]

class FilterModule:
    def filters(self):
        return {"to_haproxy_backend": to_haproxy_backend}

The function is plain Python — it takes the value piped into it plus any arguments, and returns the transformed value. The filters() method is the registration: its dictionary maps the Jinja2 name to the function, and from then on the filter is usable in any template the play renders.

Lookup Plugins

A lookup plugin is invoked as {{ lookup('larkspur.web.app_version', env) }} and fetches data at templating time from a source Ansible does not natively read — an internal release API, a custom secrets store, a database. It returns a value into a variable and runs on the control node every time it is referenced. This is the plugin you reach for when a task needs a piece of external data before it runs, because a lookup feeds variables on the way in, where a callback only sees results on the way out.

Callback Plugins

Callback plugins hook the play's lifecycle events — v2_runner_on_ok, v2_runner_on_failed, v2_playbook_on_stats — and are how you ship per-task results to a logging system, post a deploy summary to Slack, or replace Ansible's default human-readable output entirely. One callback can be the stdout callback that owns the on-screen output; others run alongside it as notification plugins. Because they fire on events as the play progresses, they are the right tool for reacting to what happened, and the wrong tool for supplying data a task needs up front.

Discovery and Packaging

Each plugin type has its own directory: filter_plugins/, lookup_plugins/, and callback_plugins/ beside a playbook, or plugins/<type>/ inside a collection. Filters and lookups are discovered and usable the moment the file is present. Callbacks are the exception — they often need explicit enabling in ansible.cfg under callbacks_enabled, which is the single most common reason a freshly written callback never seems to fire. Collection plugins are addressed by FQCN, the same as modules.