Writing Custom Ansible Modules, In Depth: AnsibleModule, argument_spec, Idempotency & check_mode

Ansible ships with thousands of modules — ansible.builtin.copy, ansible.builtin.service, community.general.ufw, amazon.aws.ec2_instance — and for the overwhelming majority of automation you will never need to write your own. But eventually you hit the wall: an internal REST API nobody has wrapped, a bespoke appliance with its own CLI, a licence server that speaks a proprietary protocol, a domain-specific resource your platform team owns. You could drive it with ansible.builtin.command or ansible.builtin.uri and a pile of register, changed_when, and failed_when glue — and that is the right first move for a one-off. But the moment that glue is copy-pasted into three playbooks, lies about changed, breaks under --check, and produces unreadable output, you have outgrown the shell-out. The clean answer is a custom module: a small Python program that takes typed parameters, talks to the thing, reports back in Ansible’s structured JSON contract, is idempotent, and honours check mode — a first-class citizen that looks and behaves exactly like the built-ins.

A module is a peculiar kind of program. You do not run it yourself; Ansible runs it on the managed node (or, for connection: local and many cloud modules, on the control node acting as the target). Ansible serialises your task’s parameters to JSON, ships your module’s code to the target, executes it with the Python interpreter found there, and reads a single line of JSON from its stdout. That JSON — changed, an optional failed, plus whatever facts and results you choose to return — is the module’s entire interface to the rest of Ansible. Get the contract right and your module composes with register, when, --check, --diff, loops, and handlers for free. Get it wrong and nothing downstream behaves. This lesson is about getting it exactly right.

This is the exhaustive version. By the end you will know when a module is the correct tool versus a role, a command/shell call, or a script; the full anatomy of a module file; AnsibleModule and every key of argument_spec — type, required, default, choices, no_log, aliases, elements, options (sub-specs), fallback, deprecated_aliases, and the apply_defaults behaviour — plus the cross-argument constraints mutually_exclusive, required_together, required_one_of, required_if, and required_by, and supports_check_mode; the return contract (module.exit_json(changed=…, **result), module.fail_json(msg=…), the conventional keys, the diff dict, returning ansible_facts, module.warn()/module.deprecate()); how to build genuine idempotency (read current state → compare to desired → change only on drift → report the truthful changed) and how to honour module.check_mode; the three placement options (library/, a role’s library/, a collection’s plugins/modules/) and the search precedence; the three documentation blocks — DOCUMENTATION, EXAMPLES, RETURN — that feed ansible-doc; module_utils for shared code and how to import it correctly; how to debug a module locally; and how to test it (sanity + unit). Everything uses FQCN and reflects current ansible-core 2.17+ / Ansible 10+ (2026). We finish with a complete, working worked module — a line-in-a-JSON-config manager — that you can drop into library/ and run for free against localhost.

Learning objectives

After working through this lesson you will be able to:

• Decide correctly when to write a module versus reach for a role, ansible.builtin.command/shell, ansible.builtin.script, or ansible.builtin.uri.
• Lay out a module file and instantiate AnsibleModule with a complete argument_spec, using every relevant key (type, required, default, choices, no_log, aliases, elements, sub-options, fallback, deprecated_aliases).
• Enforce cross-argument rules — mutually_exclusive, required_together, required_one_of, required_if, required_by — and declare supports_check_mode.
• Return results through the module contract — exit_json/fail_json, the meaning of changed, the diff structure, returning ansible_facts, and warn/deprecate.
• Implement true idempotency (gather current state, compare, act only on drift) and make the module behave correctly under --check by honouring module.check_mode.
• Place a module in library/, a role’s library/, or a collection’s plugins/modules/, and explain the discovery precedence.
• Write the DOCUMENTATION, EXAMPLES, and RETURN YAML blocks so ansible-doc and ansible-doc --snippet work, and share code via module_utils.
• Debug a module locally and run sanity and unit tests against it.

Prerequisites & where this fits

You should be fluent with everything up to the Developing tier of this course: writing playbooks, using register to capture results, the changed_when/failed_when overrides (which exist precisely because command/shell cannot judge change for themselves), roles (your module may live inside one), and collections (the production home for a module — see the roles & collections lesson). You also need working Python 3 — modules are Python programs, though the Python here is deliberately plain (standard library, a try/except, a dictionary or two). You do not need to be a Python expert; the AnsibleModule helper does the heavy lifting of argument parsing, type-checking, and JSON I/O. In the Ansible Zero-to-Hero ladder this is the first Developing lesson — the step from using Ansible’s building blocks to building new ones. It follows the debugging lesson (you will lean on --check, --diff, and -vvv to develop a module) and leads directly into Ansible plugins (filter/lookup/callback/connection — code that, unlike modules, runs on the control node). The distinction between a module (runs on the target, does a unit of work, reports changed) and a plugin (runs on the control node, extends Ansible itself) is the spine of the whole Developing tier, so fix it now. Everything in this lesson is free — the lab runs against localhost.

Core concepts

Six ideas carry the lesson; internalise them before the code.

A module is a program Ansible runs on the target, not on the control node. When a task invokes your module, Ansible takes the module’s Python source plus a small bundle of module_utils, packages it (the “AnsiBallZ” wrapper), copies it to the managed node’s temp directory, runs it with the target’s Python interpreter (the one resolved by ansible_python_interpreter), then deletes it. Your module reads its parameters from a file Ansible wrote next to it and prints exactly one JSON object to stdout. This is the opposite of a plugin (filter, lookup, callback, connection), which runs inside the Ansible process on the control node. If your code needs the target’s filesystem, packages, services, or local CLI — it is a module. If it transforms data for the playbook or hooks Ansible’s own behaviour — it is a plugin.

The return JSON is the entire interface. Ansible does not inspect your module’s exit code in any nuanced way, nor parse free text. It reads one JSON document. The keys it understands are changed (did this task alter the system?), failed (did it error?), msg (human-readable message), ansible_facts (variables to inject into the host), diff (before/after for --diff), warnings, deprecations, and invocation (echo of the parameters, added for you). Every other key you return becomes available under the task’s registered variable. Get this contract right and register, when, loops, handlers (changed drives notify), --check, and --diff all work automatically.

changed must be the truth. The single most important value your module returns is changed. It must be true only if the module actually altered the managed system on this run, and false if the system was already in the desired state. This is what makes Ansible declarative: a second run of the same play reports changed=0 because nothing needed doing. A module that always returns changed=true is a bug — it breaks the idempotence test, fires handlers needlessly, and lies in reports. The discipline is: read the current state, compare it with the requested state, and set changed based on whether they differed.

Check mode is a contract, not a freebie. When the user runs --check (dry run), Ansible sets module.check_mode = True. Your module must then predict what it would do — compute the would-be changed — without making any change. You opt in by declaring supports_check_mode=True; if you do not, Ansible skips your module entirely under --check (it shows skipping rather than risk an unsafe write). Supporting check mode well is a hallmark of a production-grade module and is explicitly graded on EX374.

Idempotency lives in your code. Built-in modules feel idempotent because their authors wrote the read-compare-change logic. Nothing about AnsibleModule makes your module idempotent automatically — if you just “do the thing” every time and return changed=true, you have written a glorified command. Idempotency is the differentiator between a real module and a shell-out, and implementing it is most of the work.

A module is documented in-band. A proper module carries three YAML strings in the file itself — DOCUMENTATION, EXAMPLES, RETURN — which ansible-doc <module> renders. This is not optional polish: the sanity tests enforce it, ansible-doc and IDE plugins read it, and it is part of the collection contract. You write the docs in the module, beside the code they describe.

Keep these terms straight, because the rest of the lesson uses them precisely.

When to write a module (versus role, command, script, or uri)

Writing a module is real engineering — Python, documentation, tests, a release in a collection. Reach for it deliberately. This decision table is the first thing an EX374 examiner (and a sensible architect) wants you to get right.

The litmus test: “Am I managing the state of a resource on a target, repeatedly, where re-running should be a no-op?” If yes — and command/uri glue is getting ugly or unreliable — write a module. If you are merely arranging existing modules, write a role. If you are transforming data for the playbook, write a plugin.

Module anatomy: the file from top to bottom

A module is a single .py file with a fixed, conventional shape. Here is the skeleton every module follows; we will fill each region in the sections that follow.

#!/usr/bin/python
# -*- coding: utf-8 -*-

# Copyright: (c) 2026, Vinod H <h.vinod@example.com>
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)

from __future__ import absolute_import, division, print_function
__metaclass__ = type

DOCUMENTATION = r'''
---
module: my_module
short_description: One-line summary
# ... full YAML, see the documentation-blocks section
'''

EXAMPLES = r'''
- name: Use the module
  namespace.collection.my_module:
    name: example
    state: present
'''

RETURN = r'''
changed:
  description: Whether the module made a change.
  type: bool
  returned: always
'''

from ansible.module_utils.basic import AnsibleModule
# (other imports: standard library, then module_utils)


def run_module():
    # 1. Declare the interface
    argument_spec = dict(
        name=dict(type='str', required=True),
        state=dict(type='str', default='present', choices=['present', 'absent']),
    )

    # 2. Instantiate the helper
    module = AnsibleModule(
        argument_spec=argument_spec,
        supports_check_mode=True,
    )

    # 3. Pull validated params
    name = module.params['name']
    state = module.params['state']

    # 4. Build the result skeleton
    result = dict(changed=False)

    # 5. Read current state, compare, act idempotently (honouring check_mode)
    #    ... the real logic ...

    # 6. Return success
    module.exit_json(**result)


def main():
    run_module()


if __name__ == '__main__':
    main()

Several conventions here are load-bearing, not decoration:

AnsibleModule and the complete argument_spec

AnsibleModule is the heart of every module. You import it, hand it your argument_spec (and the cross-argument rules), and it: parses the JSON parameters Ansible passed, type-checks and coerces each one, applies defaults, enforces required/choices/mutual-exclusion rules (failing cleanly with a good msg if violated), strips no_log values from logs, and exposes the clean values on module.params. It also gives you module.check_mode, module.exit_json(), module.fail_json(), module.warn(), module.run_command(), and a pile of filesystem helpers.

module = AnsibleModule(
    argument_spec=argument_spec,
    supports_check_mode=True,
    mutually_exclusive=[('content', 'src')],
    required_one_of=[('content', 'src')],
    required_if=[('state', 'present', ('name',))],
    required_together=[('username', 'password')],
    required_by={'auth_token': ('endpoint',)},
)

Per-argument keys

Each entry in argument_spec is a dict describing one parameter. This is the complete reference table — memorise it; every key here appears on the EX374 syllabus.

A worked argument_spec showing the common keys together:

argument_spec = dict(
    path=dict(type='path', required=True),
    key=dict(type='str', required=True),
    value=dict(type='raw'),                       # accept any JSON type
    state=dict(type='str', default='present',
               choices=['present', 'absent']),
    backup=dict(type='bool', default=False),
    mode=dict(type='str'),                         # file mode, e.g. "0644"
    api_token=dict(type='str', no_log=True,
                   fallback=(env_fallback, ['MY_API_TOKEN'])),
    tags=dict(type='list', elements='str', default=[]),
    owner=dict(type='dict', options=dict(           # nested sub-spec
        name=dict(type='str', required=True),
        team=dict(type='str', default='platform'),
    )),
    pkg=dict(type='str', aliases=['package', 'name']),
)

The cross-argument constraints

Beyond per-argument rules, AnsibleModule enforces relationships between arguments. You pass these as lists of tuples (or a dict for required_by) to the constructor; violations fail the task cleanly before your logic runs. This is the second half of the validation story and a frequent exam question.

These compose: a typical “create a thing” module declares state with choices, then required_if=[('state','present',('name',))] so name is mandatory only when creating, and mutually_exclusive=[('content','src')] so the caller picks one content source. Declaring the rules here means you never write if not module.params['name']: module.fail_json(...) by hand — AnsibleModule does it, with consistent error messages.

supports_check_mode and other constructor flags

add_file_common_args=True is the idiomatic way to give your module the same mode/owner/group controls as the file modules — Ansible adds those to your argument_spec and you apply them with module.set_fs_attributes_if_different(file_args, changed). The worked module below uses it.

The return contract: exit_json, fail_json, and the keys Ansible understands

When your module is done, it must end with exactly one of two calls. Both serialise a JSON object to stdout and exit — you never print() or return results yourself.

# Success — print the result JSON and exit(0)
module.exit_json(changed=True, msg="Created", item={"id": 42}, diff=diff)

# Failure — print {"failed": true, "msg": ...} and exit(1)
module.fail_json(msg="API returned 500", status=500, body=text)

exit_json(**result) is the success path; fail_json(msg=…, **extra) is the failure path (msg is required on failure — always give a useful one). Both accept arbitrary extra keys, which flow back to the play.

The keys Ansible interprets specially

A subtle but important point: whatever extra keys you return are your module’s public output API. Document them in the RETURN block, keep their names and types stable across releases, and put your real result under clearly-named keys (e.g. record, output, path) rather than dumping a bag of internals. Returning ansible_facts versus a plain key is a deliberate choice: use ansible_facts when the value should become an ambient host variable (like a discovered version); use a plain key (consumed via register) when it is the result of this task that the next task will reference.

module.warn(message) surfaces a non-fatal warning in the output (and the warnings list). module.deprecate(message, version=…, date=…, collection_name=…) records a deprecation. Use both rather than building the lists by hand — they integrate with Ansible’s display and --diff/JSON output.

Idempotency and check_mode: the part that makes it a real module

This is the core skill. A module that always acts is not a module — it is command with extra steps. Genuine idempotency follows a fixed four-step shape, and check-mode support is woven through it.

The idempotency algorithm:

1. Read the current state of the resource (read the file, query the API, inspect the service). This is a read-only operation and is always safe to do, even in check mode.
2. Compute the desired state from the parameters.
3. Compare. If current already equals desired, set changed=False and return — do nothing. This is the path a re-run takes; it is what produces changed=0 on the second run.
4. If they differ, and not in check mode, make the change, then set changed=True. If in check mode, set changed=True but skip the actual write — you are predicting, not doing.

In code, the pattern is unmistakable:

result = dict(changed=False)

current = read_current_state(module)          # step 1 — read-only, always safe
desired = build_desired_state(module.params)  # step 2

if current == desired:                         # step 3 — already converged
    module.exit_json(**result)                 # changed stays False

# step 4 — drift detected
result['changed'] = True
result['diff'] = {'before': to_text(current), 'after': to_text(desired)}

if module.check_mode:                           # predict only
    module.exit_json(**result)                  # changed=True, no write performed

apply_change(module, desired)                   # the only mutating call in the module
module.exit_json(**result)

Three rules make this correct:

• Never mutate before the check_mode gate. All reads happen first; the single mutating call sits after the if module.check_mode: module.exit_json(...) guard. If any write can happen before that guard, --check is unsafe and your supports_check_mode=True is a lie.
• changed reflects reality, even in check mode. Under --check you still set changed=True when you would have changed something — that is the whole point of a dry run (it tells the operator “this run would change 3 things”). You just do not perform the write.
• Build the diff from current vs desired, so --diff shows exactly what would change. The diff is computed the same way in check mode and real mode.

The absent direction follows the same shape mirrored: read current; if the resource is already gone, changed=False; if it exists, changed=True and (unless check mode) delete it.

This table summarises module behaviour across the run modes:

Module placement: library/, role library/, collection plugins/modules/

A module is discovered by filename = module name (minus .py) on Ansible’s module search path. There are three places to put one, in increasing order of “production-ready”, and a clear precedence between them.

Precedence in one sentence: an adjacent library/ module wins over a role library/ module, which wins over a collection module, which wins over the built-in of the same name — local development overrides always take priority, which is exactly what you want while iterating. For anything you intend to share or keep, the collection (plugins/modules/my_module.py, called as namespace.collection.my_module) is the right home; it gives you a stable FQCN, room for module_utils and tests, and a release process. Use a bare library/ for prototyping and for genuinely project-private one-offs.

A note on module_utils placement that mirrors this: project-level shared code goes in a module_utils/ directory beside library/; collection shared code goes in plugins/module_utils/ and is imported as ansible_collections.<ns>.<coll>.plugins.module_utils.<name>.

DOCUMENTATION, EXAMPLES, and RETURN: the three YAML blocks

These three top-level strings turn a script into a documented module. ansible-doc my_module parses them (without importing the module) to render help; ansible-doc --snippet my_module builds a task stub from DOCUMENTATION; the sanity tests validate them against a schema. Write them carefully — they are the user-facing spec.

DOCUMENTATION

Describes the module and every option. The key fields:

DOCUMENTATION: r'''
---
module: json_config
short_description: Manage a key in a JSON configuration file idempotently
version_added: "1.0.0"
description:
  - Ensures a given key in a JSON file is present with a value, or absent.
  - Idempotent and supports check mode and diff.
options:
  path:
    description: Absolute path to the JSON file. Created if missing.
    type: path
    required: true
  key:
    description: The top-level key to manage.
    type: str
    required: true
  value:
    description: The desired value for O(key). Required when O(state=present).
    type: raw
  state:
    description: Whether the key should be V(present) or V(absent).
    type: str
    choices: [present, absent]
    default: present
  backup:
    description: Create a timestamped backup before changing the file.
    type: bool
    default: false
attributes:
  check_mode:
    support: full
  diff_mode:
    support: full
author:
  - Vinod H (@kloudvin)
'''

(The O(...), V(...), C(...), R(...) macros are the current Ansible documentation markup for option names, values, code, and links — preferred over the older I()/C() style and validated by the sanity tests.)

EXAMPLES

A YAML list of runnable example tasks, using the FQCN. These are copy-paste fodder for users and are also schema-checked.

EXAMPLES: r'''
- name: Ensure a feature flag is enabled
  kloudvin.platform.json_config:
    path: /etc/myapp/config.json
    key: feature_x_enabled
    value: true
    state: present

- name: Remove a deprecated setting, with a backup
  kloudvin.platform.json_config:
    path: /etc/myapp/config.json
    key: legacy_mode
    state: absent
    backup: true
'''

RETURN

Documents every key your module returns (beyond the universal ones). Each entry gives description, type, returned (when it appears — always, on success, changed, etc.), and a sample.

RETURN: r'''
changed:
  description: Whether the file was modified.
  type: bool
  returned: always
  sample: true
path:
  description: The path that was managed.
  type: str
  returned: always
  sample: /etc/myapp/config.json
diff:
  description: Before/after of the file content.
  type: dict
  returned: when changed and --diff
'''

Together these three blocks mean ansible-doc kloudvin.platform.json_config produces full, accurate help — the same experience as a built-in module — and the sanity tests pass.

module_utils: sharing code across modules

When you write more than one module they will share code — an API client, auth handling, a to_native helper, common argument fragments. That shared Python belongs in module_utils, not copy-pasted into each module. Crucially, module_utils is also the only extra code Ansible bundles and ships to the target alongside your module (via AnsiBallZ) — so anything your module imports from module_utils just works on the managed node, whereas an arbitrary third-party import would not be shipped.

A tiny example — a shared client in module_utils/myapi.py:

# module_utils/myapi.py
from __future__ import absolute_import, division, print_function
__metaclass__ = type


class MyApiClient(object):
    def __init__(self, module, endpoint, token):
        self.module = module
        self.endpoint = endpoint
        self.token = token

    def get(self, resource):
        # use module.run_command or open_url; raise/return as needed
        ...

…imported and used in a module:

from ansible.module_utils.basic import AnsibleModule
from ansible.module_utils.myapi import MyApiClient   # project-level import
# (collection: from ansible_collections.kloudvin.platform.plugins.module_utils.myapi import MyApiClient)

Two rules: (1) keep the from __future__ … / __metaclass__ boilerplate in module_utils files too (sanity tests check them), and (2) only import from the standard library and from module_utils inside a module — anything else will not be shipped to the target and will fail with ImportError there. If your module genuinely needs a third-party library (e.g. requests), guard the import and fail_json with a helpful message if it is missing:

try:
    import requests
    HAS_REQUESTS = True
except ImportError:
    HAS_REQUESTS = False
# ...
if not HAS_REQUESTS:
    module.fail_json(msg="The 'requests' library is required. Install it on the target.")

The complete worked module

Here is the whole thing — a real, idempotent, check-mode-aware module that manages one top-level key in a JSON file. It uses only the standard library (so it ships and runs anywhere Ansible runs), demonstrates the full argument_spec, the cross-argument rules, the read-compare-change idempotency loop, check-mode prediction, the diff dict, file-attribute handling via add_file_common_args, a backup, and the three documentation blocks. Drop it in library/json_config.py and the lab below runs it.

#!/usr/bin/python
# -*- coding: utf-8 -*-

# Copyright: (c) 2026, Vinod H (@kloudvin)
# GNU General Public License v3.0+ (see https://www.gnu.org/licenses/gpl-3.0.txt)

from __future__ import absolute_import, division, print_function
__metaclass__ = type

DOCUMENTATION = r'''
---
module: json_config
short_description: Manage a top-level key in a JSON configuration file idempotently
version_added: "1.0.0"
description:
  - Ensures a top-level key in a JSON file is present with a given value, or absent.
  - Reads the current file, compares against the desired state, and only writes on drift.
  - Fully idempotent; supports check mode and diff; can manage file attributes and take a backup.
options:
  path:
    description: Absolute path to the JSON file. Created (with an empty object) if missing and O(state=present).
    type: path
    required: true
  key:
    description: The top-level key to manage.
    type: str
    required: true
  value:
    description: Desired value for O(key). Required when O(state=present). May be any JSON type.
    type: raw
  state:
    description: Whether O(key) should be V(present) or V(absent).
    type: str
    choices: [present, absent]
    default: present
  backup:
    description: Create a timestamped C(.bak) copy before modifying the file.
    type: bool
    default: false
extends_documentation_fragment:
  - ansible.builtin.files
attributes:
  check_mode:
    support: full
  diff_mode:
    support: full
author:
  - Vinod H (@kloudvin)
'''

EXAMPLES = r'''
- name: Enable a feature flag
  kloudvin.platform.json_config:
    path: /etc/myapp/config.json
    key: feature_x_enabled
    value: true
    state: present
    mode: "0644"

- name: Remove a deprecated setting with a backup
  kloudvin.platform.json_config:
    path: /etc/myapp/config.json
    key: legacy_mode
    state: absent
    backup: true
'''

RETURN = r'''
changed:
  description: Whether the file was modified.
  type: bool
  returned: always
  sample: true
path:
  description: The path that was managed.
  type: str
  returned: always
  sample: /etc/myapp/config.json
backup_file:
  description: Path of the backup, if one was taken.
  type: str
  returned: when backup is true and a change was made
  sample: /etc/myapp/config.json.2026-06-15@10:00:00~
'''

import json
import os

from ansible.module_utils.basic import AnsibleModule
from ansible.module_utils.common.text.converters import to_native


def read_config(module, path):
    """Read and parse the JSON file; return a dict. Missing file => empty dict."""
    if not os.path.exists(path):
        return {}
    try:
        with open(path, 'r') as fh:
            data = json.load(fh)
    except ValueError as exc:
        module.fail_json(msg="File %s is not valid JSON: %s" % (path, to_native(exc)))
    except (IOError, OSError) as exc:
        module.fail_json(msg="Could not read %s: %s" % (path, to_native(exc)))
    if not isinstance(data, dict):
        module.fail_json(msg="Top level of %s must be a JSON object" % path)
    return data


def write_config(module, path, data):
    """Atomically write the dict back as pretty JSON, preserving Ansible's temp-file semantics."""
    tmp = module.tmpdir and os.path.join(module.tmpdir, 'json_config.tmp') or (path + '.tmp')
    try:
        with open(tmp, 'w') as fh:
            json.dump(data, fh, indent=2, sort_keys=True)
            fh.write('\n')
    except (IOError, OSError) as exc:
        module.fail_json(msg="Could not write temp file: %s" % to_native(exc))
    module.atomic_move(tmp, path)


def run_module():
    argument_spec = dict(
        path=dict(type='path', required=True),
        key=dict(type='str', required=True),
        value=dict(type='raw'),
        state=dict(type='str', default='present', choices=['present', 'absent']),
        backup=dict(type='bool', default=False),
    )

    module = AnsibleModule(
        argument_spec=argument_spec,
        supports_check_mode=True,                       # we honour check_mode below
        add_file_common_args=True,                      # gives us mode/owner/group/etc.
        required_if=[('state', 'present', ('value',))],  # value mandatory when creating
    )

    path = module.params['path']
    key = module.params['key']
    value = module.params['value']
    state = module.params['state']
    backup = module.params['backup']

    result = dict(changed=False, path=path)

    # 1. READ current state (always safe, even in check mode)
    current = read_config(module, path)
    existed = key in current

    # 2/3. COMPARE current vs desired
    if state == 'present':
        needs_change = (not existed) or (current.get(key) != value)
    else:  # absent
        needs_change = existed

    if not needs_change:
        module.exit_json(**result)                      # already converged: changed stays False

    # Build the desired dict and a diff for --diff
    desired = dict(current)
    if state == 'present':
        desired[key] = value
    else:
        desired.pop(key, None)

    result['changed'] = True
    if module._diff:
        result['diff'] = {
            'before': json.dumps(current, indent=2, sort_keys=True) + '\n',
            'after': json.dumps(desired, indent=2, sort_keys=True) + '\n',
        }

    # 4. ACT — but only past the check-mode gate
    if module.check_mode:
        module.exit_json(**result)                      # predict only; no write

    if backup and os.path.exists(path):
        result['backup_file'] = module.backup_local(path)

    write_config(module, path, desired)

    # Apply file attributes (mode/owner/group/…) the same way copy does, and fold into changed
    file_args = module.load_file_common_arguments(module.params)
    result['changed'] = module.set_fs_attributes_if_different(file_args, result['changed'])

    module.exit_json(**result)


def main():
    run_module()


if __name__ == '__main__':
    main()

Walk through what makes this a real module and not a shell-out: the argument_spec types and validates every input (with required_if making value mandatory only for present); add_file_common_args plus set_fs_attributes_if_different give it the same mode/owner/group controls as copy; the read → compare → (return unchanged | act) structure makes it idempotent so a second run reports changed=False; the module.check_mode gate sits before any write, so --check is genuinely safe; the diff (built only when module._diff is set) makes --diff show exactly what would change; module.atomic_move and module.backup_local reuse Ansible’s safe-write and backup helpers; and the three doc blocks make ansible-doc work. Notice there is no print() and no return of results — every exit goes through exit_json/fail_json.

The diagram traces the full round trip: how a task’s parameters become a packaged payload, how the module validates and runs on the target, where the check-mode gate and the read-compare-change loop sit, and how the single JSON return flows back to drive register, --diff, and handlers on the control node.

Hands-on lab

You will write the worked module to library/, then drive it from a playbook to prove idempotency, check mode, and diff — entirely on localhost, cost ₹0.

1. Project layout

Create a working directory and drop the module in library/ (copy the complete worked module above into library/json_config.py):

mkdir -p ~/ansible-module-lab/library
cd ~/ansible-module-lab
# create library/json_config.py with the worked module's contents (your editor)

Add a minimal ansible.cfg so the local library/ is on the path (it is by default when adjacent, but being explicit helps):

# ansible.cfg
[defaults]
inventory = localhost,
library = ./library
host_key_checking = False

2. Confirm Ansible sees the module and its docs

ansible-doc -M ./library json_config

Expected: the rendered help — short description, the path/key/value/state/backup options, the file-attribute options (from the doc fragment), and check_mode/diff support. If ansible-doc errors, your DOCUMENTATION YAML is malformed — fix it before going further (this is exactly how the doc block earns its keep).

Generate a task snippet:

ansible-doc -M ./library --snippet json_config

3. A playbook that exercises every behaviour

Create play.yml:

---
- name: Exercise the custom json_config module
  hosts: localhost
  gather_facts: false
  vars:
    cfg: /tmp/myapp.json
  tasks:
    - name: First run — create the key (should report CHANGED)
      json_config:
        path: "{{ cfg }}"
        key: feature_x_enabled
        value: true
        state: present
        mode: "0644"
      register: first

    - name: Second run — identical (should report OK, changed=false)
      json_config:
        path: "{{ cfg }}"
        key: feature_x_enabled
        value: true
        state: present
        mode: "0644"
      register: second

    - name: Assert idempotency
      ansible.builtin.assert:
        that:
          - first.changed | bool
          - not (second.changed | bool)
        success_msg: "Idempotent: first run changed, second did not."

    - name: Show the managed path the module returned
      ansible.builtin.debug:
        var: second.path

4. Run it and read the results

ansible-playbook play.yml

Expected: the first task is changed (yellow), the second is ok (green), and the assert passes — proof of idempotency. Inspect the file:

cat /tmp/myapp.json
# {
#   "feature_x_enabled": true
# }

5. Prove check mode and diff

Run again, changing the value, in check + diff mode:

ansible-playbook play.yml --check --diff -e '{"_unused":0}' \
  --extra-vars 'cfg=/tmp/myapp.json'

Now flip the value to test prediction without writing — edit the first task’s value: true to value: false and run:

ansible-playbook play.yml --check --diff
cat /tmp/myapp.json     # STILL shows true — check mode wrote nothing

Expected: the play reports the task as changed and --diff prints a before/after showing true → false, but the file on disk is unchanged — exactly the contract: predict, do not act. Run the same without --check and the file updates and a re-run goes green again.

6. Validation checklist

• ansible-doc -M ./library json_config renders full help → the doc blocks are valid.
• First run changed, second run ok → idempotency works.
• --check --diff shows the diff but leaves /tmp/myapp.json untouched → check mode is honoured.
• registered second.path prints the path → the extra return key flows back to the play.

7. Cleanup

rm -rf ~/ansible-module-lab /tmp/myapp.json /tmp/myapp.json.*~

Cost note: ₹0. Everything ran against localhost with ansible-core; no cloud resources, no managed nodes, nothing to deallocate.

Common mistakes & troubleshooting

Best practices

• Idempotency is the spec, not a feature. Always read-compare-change; a re-run of any module must report changed=False. Treat the idempotence test (run twice, second run changed=0) as the acceptance criterion.
• Support check mode and diff, and advertise it in the attributes: doc block. Gate all writes behind the check_mode guard; build a meaningful diff.
• Validate at the edge with argument_spec. Use type, choices, required, no_log, and the cross-argument rules (required_if, mutually_exclusive, …) so AnsibleModule rejects bad input with clean messages — never hand-roll validation you can declare.
• Exit only through exit_json/fail_json. No print(), no sys.exit(), no return of results. Pass a useful msg to fail_json.
• Use Ansible’s helpers: module.run_command() for shelling out (it handles quoting, env, and returns rc/stdout/stderr), module.atomic_move() for safe writes, module.backup_local() for backups, add_file_common_args + set_fs_attributes_if_different for file attributes, env_fallback for env-var defaults.
• Import only stdlib and module_utils. Put shared code in module_utils; guard genuinely-needed third-party libraries and fail cleanly if absent.
• Write all three doc blocks and keep DOCUMENTATION.options in lockstep with argument_spec. Document every return key in RETURN — those keys are your public API; keep them stable.
• Ship modules in a collection (plugins/modules/, called by FQCN) once they outgrow a one-off; use library/ only for prototyping and truly project-private modules.
• Keep modules single-purpose and stateless between runs — they read the world, converge one resource, and report. Orchestration belongs in roles/playbooks, not inside a module.

Security notes

• Scrub secrets with no_log=True on every credential/token/password argument. AnsibleModule then removes the value from -v output, the invocation echo, and logs. Never include a secret in msg, a returned key, or a print().
• Prefer module.run_command([...] , ...) with an argument list over a shell string — passing a list avoids shell interpolation and command-injection from untrusted parameters. Avoid use_unsafe_shell=True.
• Validate and constrain inputs (choices, type='path', explicit checks) so a malicious or fat-fingered parameter cannot make the module do something dangerous (path traversal, writing outside an expected directory).
• Write atomically and back up (atomic_move, backup_local) so a failure cannot leave a half-written config or destroy the previous good file.
• Honour no_log on whole tasks too: a caller can set no_log: true on the task; your module should not defeat that by echoing inputs. Returning the secret in a key would surface it under register — do not.
• Mind check_mode for read safety: even your read path should avoid side effects (don’t create resources “to inspect them”); a --check run must be safe to run against production.
• Pin and review module_utils you import — shared code runs with the module’s privileges on the target. Treat it as part of your trusted computing base, especially in a shared collection.

Interview & exam questions

1. Where does a module run, and how does that differ from a plugin? A module runs on the managed node (or the control node acting as target for local connections): Ansible bundles it via AnsiBallZ, ships it, runs it with the target’s Python, and reads one JSON line from stdout. A plugin runs in the Ansible process on the control node, extending Ansible itself (filter, lookup, callback, connection). “Does work on the target → module; transforms data/hooks Ansible → plugin.”
2. What is the module’s return contract, and which keys does Ansible interpret specially? The module prints one JSON object. Ansible specially understands changed, failed, msg, ansible_facts, diff, warnings, deprecations, and invocation; every other key flows back under the task’s register. You finish with module.exit_json(**result) (success) or module.fail_json(msg=…) (failure) — never print()/return.
3. How do you make a module idempotent? Read the current state, compare it to the desired state from the params, and act only if they differ, setting changed from the comparison. If already converged, return changed=False. This is what makes a second run report changed=0.
4. What does supports_check_mode=True do, and what must you also do? It tells Ansible the module is safe under --check (without it, the task is skipped in check mode). You must also honour module.check_mode: compute the would-be changed and build the diff, but gate every write behind if module.check_mode: module.exit_json(...) so nothing is actually changed.
5. List five argument_spec keys and what each does. type (declare/coerce the type), required (must be supplied), default (value when omitted), choices (enumerated valid values), no_log (scrub from output/logs); plus aliases, elements (item type for lists), options (nested sub-spec for dicts), and fallback (e.g. env_fallback).
6. Name the cross-argument constraints and give an example use. mutually_exclusive (at most one — e.g. content/src), required_together (all-or-none — username/password), required_one_of (at least one — content/src), required_if (X==V ⇒ others required — state==present ⇒ name), required_by (X set ⇒ others required — auth_token ⇒ endpoint). They let AnsibleModule validate relationships so you don’t hand-code the checks.
7. What are the three documentation blocks and why are they top-level strings? DOCUMENTATION (the module + every option), EXAMPLES (runnable FQCN tasks), and RETURN (every returned key). They are module-level assignments (raw strings) so ansible-doc can extract them by parsing the file without importing it; the sanity tests validate them, and DOCUMENTATION.options must mirror argument_spec.
8. Where can a module live, and what is the precedence? Adjacent library/ (project-wide; searched first, overrides built-ins), a role’s library/ (while that role runs), and a collection’s plugins/modules/ (production, addressed by FQCN). Local library/ wins over role library/ wins over collection wins over built-in — local overrides take priority.
9. What is module_utils for, and what is special about it? Shared Python imported by modules. It is the only extra code AnsiBallZ ships to the target alongside the module, so imports from module_utils work on the managed node (arbitrary third-party imports do not). Project: module_utils/<name>.py → from ansible.module_utils.<name> import …; collection: plugins/module_utils/ → from ansible_collections.<ns>.<coll>.plugins.module_utils.<name> import ….
10. How do you return a value that becomes a host variable versus one consumed by register? Return it under ansible_facts to inject it as an ambient host variable (no register needed); return it under any other key to expose it through the task’s **register**ed result. Use ansible_facts for discovered/ambient state, a plain key for this task’s result.
11. How should a module shell out, and why does it matter for security? Use module.run_command([...] ) with an argument list (not a shell string) — it handles quoting/env, returns (rc, stdout, stderr), and avoids shell injection from untrusted params. Avoid use_unsafe_shell=True. For secrets, set no_log=True so values are scrubbed.
12. You added print("debug") and the module breaks with a JSON error — why? The return contract requires only the final JSON on stdout. Any extra stdout corrupts it. Use module.warn(), module.debug(), -vvv, or return a debug key via exit_json instead of print().

Quick check

1. After your module determines the system is already in the desired state, what value must changed be, and what does that prove on a second run?
2. Which constructor flag must you set so --check does not skip your module, and what must you do in the code to back it up?
3. Name the two methods a module must use to finish — one for success, one for failure — and the one argument the failure method requires.
4. You import requests at the top of a module and it works on the control node but fails on the target. Why, and what is the fix?
5. Which return key turns a value into an ambient host variable that the rest of the play can use without register?

Answers

1. changed=False — and a second, identical run reporting changed=0 is the proof of idempotency. Set changed from the read-vs-desired comparison, never unconditionally.
2. supports_check_mode=True in AnsibleModule(...). You must also honour module.check_mode: gate every mutating call behind if module.check_mode: module.exit_json(**result) so check mode predicts (changed=True if it would change) but never writes.
3. module.exit_json(**result) for success and module.fail_json(msg=…) for failure; fail_json requires msg. Never print() or return results.
4. Ansible ships only the standard library and module_utils to the target (via AnsiBallZ); arbitrary third-party imports are not bundled, so requests is absent on the managed node. Fix: vendor the needed code into module_utils, or guard the import (try/except ImportError, HAS_REQUESTS) and fail_json with an install hint.
5. ansible_facts — returning a dict under ansible_facts injects those keys as host variables for the rest of the play (no register needed).

Exercise

Extend the worked json_config module into a small but production-shaped piece of work (cost ₹0, all on localhost). (a) Add a new parameter present_only_if_absent of type='bool' default false; when true and state: present, the module must not overwrite an existing key (it should report changed=False if the key already exists with any value) — implement this with the read-compare logic, not a post-hoc check. (b) Add a value validation: if state: present and the existing value is a dict but the new value is a scalar, fail_json with a clear message — and prove the message is helpful by triggering it. © Add full diff output for the absent path and confirm --diff shows the key being removed. (d) Move the read_config/write_config helpers into module_utils/json_state.py and import them, proving the module still runs (this exercises the module_utils shipping mechanism). (e) Write a second playbook that runs the module twice with --check and uses ansible.builtin.assert to prove the file on disk never changed in check mode. (f) Run ansible-doc -M ./library json_config after every change and keep DOCUMENTATION.options in sync with the argument_spec — note in one sentence what ansible-doc does when they drift. (g) Clean up. In two sentences, explain why the new behaviour belongs in the read-compare step (so changed stays truthful and check mode keeps working) rather than being bolted on after the write.

Certification mapping

• EX374 (Red Hat Certified Specialist in Developing Automation with Ansible Automation Platform) — “Create Ansible plugins and modules”: this lesson maps directly. Expect to write a module with a correct argument_spec (types, required, choices, no_log, cross-argument rules), make it idempotent, support check mode (supports_check_mode + honouring module.check_mode), return results via exit_json/fail_json, write the DOCUMENTATION/EXAMPLES/RETURN blocks, and place it correctly (collection plugins/modules/, addressed by FQCN). Knowing module_utils and the build/test flow is part of the objective.
• EX374 — “Manage content collections”: modules in production live in a collection (plugins/modules/, plugins/module_utils/), versioned and distributed — the placement and FQCN material here is the entry point to that objective.
• RHCE (EX294): writing modules is not an RHCE objective, but RHCE-level fluency with idempotency, changed_when/failed_when, register, and --check/--diff is the prerequisite mindset — this lesson formalises those into the module contract.
• Beyond the exams: the same skills underpin building plugins (next lesson — control-node code) and shipping collections and execution environments, which is how platform teams package and distribute custom automation in Automation Platform (AAP).

Glossary

• Module — a program Ansible ships to and runs on the target; performs a unit of work and returns a single JSON object with changed.
• Plugin — code that runs on the control node, extending Ansible itself (filter, lookup, callback, connection, …); the subject of the next lesson.
• AnsibleModule — the helper class (ansible.module_utils.basic) that parses/validates parameters, handles JSON I/O, and provides exit_json, fail_json, check_mode, run_command, and filesystem helpers.
• argument_spec — the dict declaring each parameter (type, required, default, choices, no_log, aliases, elements, options, fallback, …).
• Cross-argument rules — relationship constraints passed to AnsibleModule: mutually_exclusive, required_together, required_one_of, required_if, required_by.
• exit_json / fail_json — the only correct ways to finish a module: print the result JSON and exit (0 for success; 1 with required msg for failure).
• changed — the boolean stating whether the module altered the system this run; drives idempotence, --check reporting, and notify/handlers.
• ansible_facts — a returned dict whose keys are injected as host variables for the rest of the play (no register needed).
• diff — a returned {'before':…, 'after':…} dict shown under --diff.
• check_mode — dry-run flag (module.check_mode); when True, predict changes (changed=True if it would change) without making them; enabled via supports_check_mode=True.
• Idempotency — the property that running a module twice changes the system at most once; implemented by the read → compare → change-only-on-drift loop.
• module_utils — shared Python imported by modules; the only extra code AnsiBallZ ships to the target alongside the module.
• AnsiBallZ — Ansible’s wrapper that bundles the module plus its module_utils into one executable payload for the managed node.
• DOCUMENTATION / EXAMPLES / RETURN — the three top-level YAML strings that document the module; parsed by ansible-doc and validated by the sanity tests.
• library/ — a directory (adjacent to a playbook or set in ansible.cfg) where project-local modules live; searched first, overriding built-ins.
• FQCN — Fully-Qualified Collection Name (namespace.collection.module); the way a module shipped in a collection is addressed.
• no_log — argument_spec flag that scrubs a parameter’s value from output, -v logs, and the invocation echo; set it on every secret.
• Sanity tests — ansible-test sanity: schema/style checks (doc presence, __future__/__metaclass__ boilerplate, FQCN, no-print, doc-vs-spec match) that a collection module must pass.

Next steps

You can now write a real, idempotent, check-mode-aware custom module end to end — choosing a module over a role/command/script/uri; instantiating AnsibleModule with a complete argument_spec and the cross-argument rules; returning results through the exit_json/fail_json contract (changed, diff, ansible_facts); implementing the read → compare → change-only-on-drift loop and honouring module.check_mode; placing the module in library/, a role’s library/, or a collection’s plugins/modules/; writing the DOCUMENTATION/EXAMPLES/RETURN blocks; and sharing code via module_utils, with debugging and sanity/unit testing on the side. The natural next move is the other half of “developing Ansible”: Ansible plugins, in depth — filter, lookup, callback, and connection plugins, the code that (unlike modules) runs on the control node and extends Ansible itself, with worked filter and lookup examples. From there, package what you have built: revisit roles & collections to bundle your module and module_utils into a versioned, FQCN-addressed collection ready for Galaxy or Automation Hub.