Exhaust the alternatives first · Ansible

Writing a custom module is one of the more satisfying things you can do with Ansible. It is also, most of the time, the wrong answer to the problem that prompted it — and the wrongness does not show up for about eighteen months.

This part covers how to write one properly, because sometimes you should. This lesson is about the decision that comes first, and it is the more consequential half.

What a custom module actually costs

The cost is not the writing. A competent Python programmer produces a working module in an afternoon, which is exactly why this decision gets made casually.

The cost is everything after the merge:

Obligation	What it means in practice
Maintenance	Somebody owns this when the target API changes, when Python deprecates a library it uses, when `ansible-core` changes the module interface
Testing	It has no upstream test suite. Yours is the only one, and if you do not write it, there is none
Documentation	`ansible-doc` shows what you wrote. A colleague reading the play at 03:00 gets your `DOCUMENTATION` block or nothing
Debuggability	When it misbehaves, the engineer on call has to read Python they have never seen, inside a payload shipped to a remote host
Correctness	Idempotency, accurate `changed`, working check mode and `no_log` are now your responsibility. Lesson 3 is the list, and every item is a way to be wrong
Bus factor	Modules are usually written by one enthusiastic person. Estimate honestly how many colleagues could modify it next year

None of that is an argument against ever writing one. It is the price tag, and the alternatives below are cheaper on every row.

The five alternatives, in order

Work down this list. Stop at the first one that fits.

1. An existing module in a collection

The most common reason for writing a module is not knowing one exists. Ansible ships thousands across the collections, and the search is worth doing properly rather than from memory.

Read-only / Safesearch the modules you actually have installed— READ-ONLY: both commands read local documentation only, no network. -l lists everything; -F prints name and source path, which is how you tell a collection module from a local one.

# Every module available on this controller, with its short description.
ansible-doc -l | grep -i firewall

# Name and file path for each - reveals which collection it came from.
ansible-doc -F | grep -i firewall

# Read the full documentation for a candidate.
ansible-doc community.general.ufw

Search Galaxy too, and apply Part XXVII’s evaluation criteria before adopting: when it was last released, how many maintainers it has, whether it has tests. A poorly maintained third-party collection is a genuine reason to prefer your own code — but that is a judgement about a specific collection, not a reason to skip the search.

2. `uri` against the thing’s API

If the target has an HTTP API — and most modern infrastructure does — uri is a full HTTP client with authentication, body serialisation, status assertions and return-value registration. Most custom modules written in the last decade are HTTP clients with a bad interface.

Configuration changea 200-line custom module, as three uri tasks— CONFIGURATION: the PUT changes state on the target service. The GET before it is read-only, and it is what makes the change conditional rather than unconditional.

- name: Read the current configuration
ansible.builtin.uri:
  url: 'https://api.example.com/v1/pools/{{ pool_name }}'
  method: GET
  headers:
    Authorization: 'Bearer {{ api_token }}'
  status_code: [200, 404]
register: pool_current
changed_when: false

- name: Apply the desired configuration
ansible.builtin.uri:
  url: 'https://api.example.com/v1/pools/{{ pool_name }}'
  method: PUT
  headers:
    Authorization: 'Bearer {{ api_token }}'
  body_format: json
  body:
    algorithm: '{{ pool_algorithm }}'
    timeout: '{{ pool_timeout }}'
  status_code: [200, 201]
when: >-
  pool_current.status == 404
  or pool_current.json.algorithm != pool_algorithm
  or pool_current.json.timeout != pool_timeout
register: pool_applied

- name: Confirm the service reports what we asked for
ansible.builtin.uri:
  url: 'https://api.example.com/v1/pools/{{ pool_name }}'
  method: GET
  headers:
    Authorization: 'Bearer {{ api_token }}'
  status_code: 200
register: pool_after
changed_when: false
failed_when: pool_after.json.algorithm != pool_algorithm

Read what that shape gives you for free. The when: is the idempotency check, written in the play where a reviewer can see it. The changed_when: false on the reads is honest, because a GET changes nothing. The failed_when on the final read is verification of outcome rather than of task success, which is Part XXVI’s discipline. And api_token is a variable, so no_log and vault handling work exactly as they do everywhere else.

3. `command` with an honest `changed_when` and `failed_when`

When the thing has a CLI and no API, command plus the precision keywords from Part XII gets you a task that reports accurately even though the underlying tool knows nothing about Ansible.

Configuration changea CLI wrapped honestly— CONFIGURATION: the second task changes state. The first is a read used to decide whether the second should run at all, which is what makes the pair idempotent.

- name: Read the current licence state
ansible.builtin.command:
  cmd: /usr/local/bin/appctl licence show --format json
register: licence_state
changed_when: false
check_mode: false

- name: Apply the licence only if it differs
ansible.builtin.command:
  cmd: /usr/local/bin/appctl licence set --key {{ licence_key | quote }}
when: (licence_state.stdout | from_json).key != licence_key
register: licence_set
changed_when: licence_set.rc == 0

check_mode: false on the read is deliberate and often forgotten: it lets the read run during a --check pass so the conditional on the second task can be evaluated, which is what makes the dry run informative rather than a pair of skips. Part XXV covers the trap in full.

This is the alternative with the most caveats, and Part LII lesson 1 catalogues what goes wrong when it is applied without them. It is still better than a module for a one-off, because the failure is visible in the play rather than hidden in Python.

4. A filter or lookup plugin

If what you actually need is a transformation — parsing a vendor format, computing an address range, reshaping a data structure — that is not a module. A module executes on the target; a filter transforms data on the controller.

Filters are dramatically cheaper than modules: a plain Python function with no state, no idempotency contract, no check-mode obligation and no changed value to get right. Lesson 5 covers the choice properly.

5. A role

If the answer is “several tasks that always go together, parameterised”, that is a role, and it is the alternative teams reach for last despite it being right most often.

A role gives you defaults, argument validation via argument_specs.yml, handlers, and a name — everything a module gives you except the illusion of atomicity, and it is written in YAML the whole team can read.

When a module genuinely is the answer

Two situations, and they are narrower than they sound.

A genuine API with no collection, used repeatedly. Internal systems qualify — an in-house provisioning API, a bespoke CMDB. The discriminator is repeatedly: three uri tasks used once is fine forever; the same three tasks copied into eleven roles is a module waiting to happen.

Logic that must run on the target and report change honestly. Something that must inspect remote state, decide, act, and return an accurate changed — where the decision needs data that only exists on the managed node and is too involved to express in a conditional. A module runs there; a filter does not.

Under the hood

Why is a module structurally more expensive than everything else on the list? Because of where it runs and what that requires.

A module is not called like a function. ansible-core collects the module file and everything it imports from module_utils, wraps it into a self-contained zip payload called AnsiballZ, ships that to the managed node over the connection, executes it there with the remote Python interpreter, and parses a single line of JSON from its stdout.

Four consequences follow, and they explain the entire cost table.

It runs on a Python you do not control. Your development machine has 3.12; the managed node might have 3.9. Every language feature and every imported library has to exist there. This is why modules depend on the standard library wherever possible, and why “it works locally” carries so little information.

Its only output channel is stdout, and it must be exactly one JSON object. A stray print(), a warning from an imported library, a traceback — anything else on stdout makes the module fail with a parse error that reports the module as returning invalid JSON rather than reporting the actual problem. Debugging that at 03:00 is the specific experience the cost table is warning about.

There is no interactive debugger. The code is executing on a remote host, inside a temporary directory that is deleted immediately afterwards. Diagnosis is -vvv, ANSIBLE_KEEP_REMOTE_FILES=1, and reading. A uri task, by contrast, is debugged by looking at the registered variable.

Nothing enforces the contract. ansible-core trusts what the module returns. If it says changed: true, handlers fire. If it declares supports_check_mode=True, core hands it a check-mode run and expects it to behave. Nothing verifies either claim, which is why lesson 3 is a contract rather than an API description.

None of this applies to uri, command, a filter or a role. That asymmetry is the whole argument of this lesson.

What happens if a collection module exists but is missing one option you need?

Three responses, and the order matters because the tempting one is third.

Check whether you actually need it. A surprising fraction of “missing option” cases are a different option spelled differently, or a default that already does what you want. ansible-doc on the exact version you have installed — not the web documentation for the newest release — is the check. Version skew between what you read and what you run is a real and common source of this.

Contribute it upstream. For a maintained collection this is often a small pull request, and it is the response with the best long-term economics: the option gets tests, documentation, review and a maintainer who is not you. The objection is timeline — you need it this sprint and the release is in two months.

The bridging move is to combine it with a temporary local workaround: do the one unsupported step with uri or command alongside the collection module, and remove that task when the release lands. You end up with a small, obviously temporary piece of play code and an upstream fix, rather than a permanent fork.

Fork the module into library/. This is the one that feels pragmatic and ages worst. You now maintain a copy that will not receive upstream fixes, and it shadows the collection version by name, so a colleague reading community.general.thing in a play may be running your fork instead. If you do it, name it differently, document why it exists, and record what you would need for it to be deleted.

Knowledge check

Why this matters

The instinct to write a module is a good instinct pointed at the wrong target. It comes from wanting the automation to be clean, named and reusable — which are the right things to want.

What this lesson argues is that Ansible already provides four cheaper ways to get them. uri gives you a real HTTP client. command with honest reporting keywords gives you a CLI wrapped truthfully. A filter gives you a transformation. A role gives you a name and an interface. All four are readable by the whole team, debuggable from the registered variable, and carry no contract you can silently violate.

The module is the only one of the five where being wrong is invisible. A module that lies about changed produces restart storms nobody traces back to it. A module that declares check-mode support and modifies anyway turns a dry run into a change on forty hosts. Both are in Part LII because both have happened repeatedly.

So the decision is not “am I capable of writing this” — you probably are, in an afternoon. It is “does this problem justify owning code with that failure surface, for as long as this repository exists”. Sometimes it does. The next lesson is for when it does.