Writing a filter plugin (and when not to) · Ansible

Occasionally the readable version of an expression does not exist, because the transformation you need is genuinely a small piece of logic rather than a chain of filters. Converting a dotted-quad netmask to a prefix length is a fair example: doable in Jinja, and the result is unreadable.

A filter plugin is about forty lines of Python. This lesson writes one end to end and then spends its second half on the more important question, which is when not to.

The rule first

A filter takes a value and returns a value. It does nothing else.

No file access. No network. No subprocess. No writing anywhere. No reading anything that is not an argument.

That is not style advice, it is a consequence of where filters run and when. A filter is evaluated during templating, on the controller, potentially many times per host, in an order you do not control, with no error handling around it beyond “the task failed”. Anything with a side effect placed there is unpredictable in exactly the way infrastructure automation must not be.

If your idea needs I/O, it is a lookup (controller-side data) or a module (target-side work). Both exist, both are documented, and choosing one of them instead is nearly always the right call.

The filter

Inside a collection, at plugins/filter/netmask.py:

Read-only / Safeplugins/filter/netmask.py

from __future__ import annotations

DOCUMENTATION = r"""
name: to_cidr
short_description: Convert a dotted-quad netmask to a prefix length
description:
- Returns the CIDR prefix length for a dotted-quad IPv4 netmask.
options:
_input:
  description: A dotted-quad netmask such as 255.255.255.0.
  type: str
  required: true
author:
- Example Corp Platform Team
"""

EXAMPLES = r"""
- name: Show the prefix length
ansible.builtin.debug:
  msg: "{{ '255.255.255.0' | example_corp.platform.to_cidr }}"
"""

RETURN = r"""
_value:
description: The prefix length.
type: int
"""

from ansible.errors import AnsibleFilterError


def to_cidr(mask):
  try:
      octets = [int(o) for o in str(mask).split('.')]
  except ValueError:
      raise AnsibleFilterError("to_cidr: %r is not a dotted-quad netmask" % (mask,))
  if len(octets) != 4 or any(o < 0 or o > 255 for o in octets):
      raise AnsibleFilterError("to_cidr: %r is not a dotted-quad netmask" % (mask,))
  bits = ''.join(format(o, '08b') for o in octets)
  if '01' in bits:
      raise AnsibleFilterError("to_cidr: %r is not contiguous" % (mask,))
  return bits.count('1')


class FilterModule(object):
  def filters(self):
      return {'to_cidr': to_cidr}

Four things in that file earn their place.

FilterModule.filters() is the entry point. It returns a mapping of filter name to callable. One file can export several related filters; do that rather than one file per filter.

AnsibleFilterError is how a filter fails. Raising it produces an error naming your filter and your message. Raising a bare ValueError produces a traceback that names Python internals and leaves the user guessing which expression caused it.

Validation before computation. Three checks — parseable integers, four octets in range, contiguous bits — before the answer. A filter that accepts nonsense and returns a plausible number is worse than one that fails, because the wrong prefix length ends up in a routing configuration.

The DOCUMENTATION block is what makes ansible-doc work. It is optional to the loader and not optional to your colleagues.

Loading it and proving it loaded

Read-only / Safeit works— Runs a play using the collection filter. The result is an integer.

$ ansible-playbook -i localhost, filter-test.yml

TASK [Use the collection filter] ***********************************************
ok: [localhost] => {
  "msg": 24
}

Read-only / Safeand it refuses bad input by name— The same filter given a non-contiguous netmask. The error names the filter and quotes the message from AnsibleFilterError.

$ ansible-playbook -i localhost, filter-test.yml

[ERROR]: Task failed: Finalization of task args for 'ansible.builtin.debug' failed: Error while resolving value for 'msg': The filter plugin 'example_corp.platform.to_cidr' failed: to_cidr: '255.0.255.0' is not contiguous
Origin: /home/opsuser/project/filter-test.yml:10:14

8     - name: Reject a bad mask
9       ansible.builtin.debug:
10         msg: "{{ '255.0.255.0' | example_corp.platform.to_cidr }}"
              ^ column 14

Filter name, your message, the file, the line and the column. That is the payoff for AnsibleFilterError and the validation, and it is what a colleague will see at 3am.

ansible-doc reads the DOCUMENTATION block:

Read-only / Safedocumented like any shipped filter— Prints the documentation for the custom filter, with the collection path on the collection search path.

$ ANSIBLE_COLLECTIONS_PATH=./collections ansible-doc -t filter example_corp.platform.to_cidr

> FILTER example_corp.platform.to_cidr (/home/opsuser/project/collections/ansible_collections/example_corp/platform/plugins/filter/netmask.py)

Returns the CIDR prefix length for a dotted-quad IPv4 netmask.

OPTIONS (red indicates it is required):

 _input  A dotted-quad netmask such as 255.255.255.0.
      type: str

AUTHOR: Example Corp Platform Team

NAME: to_cidr

EXAMPLES:
- name: Show the prefix length
ansible.builtin.debug:
  msg: "{{ '255.255.255.0' | example_corp.platform.to_cidr }}"

RETURN VALUES:

 _value  The prefix length.
      type: int

Testing it

A filter is a pure function, which makes it unusually easy to test — no hosts, no connections, no state:

Read-only / Safefilter-tests.yml

- name: Tests for example_corp.platform.to_cidr
hosts: localhost
gather_facts: false
vars:
  cases:
    - { mask: '255.255.255.0',   expect: 24 }
    - { mask: '255.255.255.255', expect: 32 }
    - { mask: '0.0.0.0',         expect: 0 }
    - { mask: '255.255.240.0',   expect: 20 }
tasks:
  - name: Known-good conversions
    ansible.builtin.assert:
      that: item.mask | example_corp.platform.to_cidr == item.expect
      fail_msg: "{{ item.mask }} gave {{ item.mask | example_corp.platform.to_cidr }}, expected {{ item.expect }}"
      success_msg: "{{ item.mask }} -> {{ item.expect }}"
    loop: "{{ cases }}"
    loop_control:
      label: "{{ item.mask }}"

Read-only / Safefour cases, no infrastructure— Runs the assertion play. It needs no managed hosts and completes in under a second, so it belongs in CI.

$ ansible-playbook -i localhost, filter-tests.yml

ok: [localhost] => (item=255.255.240.0) => {
  "changed": false,
  "item": {
      "expect": 20,
      "mask": "255.255.240.0"
  },
  "msg": "255.255.240.0 -> 20"
}

PLAY RECAP *********************************************************************
localhost                  : ok=1    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

Add the failure cases too — 255.0.255.0, 256.0.0.0, '' — with ignore_errors and a check that they did fail, or as a separate play you expect to fail. A filter’s error handling is the half that gets broken by a later change.

For anything more substantial, ansible-test units runs pytest against a collection’s tests/unit/ directory, and a pure function is the easiest thing in Ansible to unit test. Part XXVI covers the testing tooling; the point here is that a filter has no excuse for being untested, because testing it needs nothing.

When not to write one

The boundaries, stated as a table:

What you need	The right tool	Why not a filter
Transform a value you already have	filter	—
Read a file, an API, an environment variable	lookup	Filters must not do I/O
Change something on a managed host	module	Filters run on the controller
Change something on the controller	module with `delegate_to`	Same
Decide yes or no about a value	test	A filter returning a boolean works, but reads worse in `when:`
Produce a host list	inventory plugin	Filters cannot be inspected before a run

A filter with a side effect runs an unknown number of times

Templating is not a single ordered pass you can reason about. An expression may be evaluated once, or once per host, or repeatedly as lazily-evaluated variables are resolved by different consumers. Nothing guarantees a count, and nothing guarantees an order.

So a filter that increments a counter, writes a file, or calls an API does that an unspecified number of times, at unspecified moments, concurrently across forks.

The failure is not theoretical and it is not consistent, which is the worst combination: it works in testing with two hosts and produces duplicate API calls or a corrupted file at fifty. There is no diagnostic that points at the filter, because the filter is not in the task output.

If you find yourself wanting I/O in a filter, the thing you want is a lookup — which is also controller-side, is documented as performing I/O, and is evaluated under the same rules but with an interface designed for it.

Why the collection FQCN matters more for plugins than for modules

A filter in plugins/filter/ of a collection is addressed as namespace.collection.name and can also be called by its short name to_cidr when the collection is in a collections: list.

The short form is more dangerous for filters than for modules, for a reason specific to how they are used: a module name sits at the start of a task where a reviewer is looking, while a filter name sits in the middle of an expression where nobody is. A to_cidr shadowed by a same-named filter in a playbook-adjacent filter_plugins/ directory is invisible in review and produces a plausible number.

Two habits close it:

Fully qualify filters from your own collections. {{ mask | example_corp.platform.to_cidr }} is longer and cannot be intercepted, exactly as ansible.builtin.copy cannot.

Do not shadow builtin names. A collection filter called combine or default will confuse everyone who reads it, whether or not resolution picks the one you meant. Name it for what it does in your domain — to_cidr, rack_of, env_prefix — and the ambiguity does not arise.

The corollary for ansible-doc: the first line of its output is the absolute path of the file it loaded, so when two filters of the same name are suspected, that command settles it — the same technique Part XXVII used for collections.

What happens if your filter raises an unexpected exception?

Not AnsibleFilterError — a KeyError, an IndexError, a ZeroDivisionError from an input you did not anticipate.

The task fails with a message that includes the Python exception type and text, which is more useful than nothing but names Python internals rather than your filter’s contract. The user sees something like “object of type ‘dict’ has no attribute” and has to work backwards to which expression produced it.

Three things to do about it:

Validate inputs at the top of the function and raise AnsibleFilterError with a message that names the filter, quotes the offending value, and says what was expected. That is three lines and it is the difference between a five-minute diagnosis and an hour.
Never catch broadly and return a default. A filter that swallows errors and returns 0, '' or None puts a wrong value into a configuration file, which is the same failure class as errors='ignore' on a lookup. Fail.
Test the failure paths, not only the happy ones. The assertion playbook above is where they go, and they are the cases that break when somebody optimises the function later.

The rule first

The filter

Loading it and proving it loaded

Testing it

When not to write one

Knowledge check