The module contract · Ansible

Everything Ansible does to a managed node, it does through a module. Understanding what a module is — precisely, not approximately — settles a surprising number of arguments about idempotency, check mode, change reporting and why shell is not just an untidy alternative to a real module.

The contract

A module is a program that:

Receives its arguments as structured data, not as a command line.
Runs on the target, under the target’s Python, as the connecting user or as whoever become made it.
Returns JSON on stdout and exits.
Declares in that JSON whether it changed anything and whether it failed.

That is the whole contract. There is no fifth clause where Ansible checks the module’s work.

Point 4 is the one with consequences. Ansible does not inspect the target to find out whether something changed. It reads the changed key the module returned and believes it. The entire reporting layer — the PLAY RECAP, handler firing, --check predictions, your change dashboards, your compliance evidence — is downstream of a claim made by a program that ran for forty milliseconds on a machine you were not watching.

The return value

Run any module and you see its JSON directly:

Read-only / Safea module return value, unedited— The stat module returns metadata about one path. The top-level keys are the contract; the stat sub-dictionary is the payload specific to this module.

$ ansible localhost -m ansible.builtin.stat -a "path=/etc/hostname"

localhost | SUCCESS => {
  "changed": false,
  "stat": {
      "atime": 1786428080.6388974,
      "checksum": "5e088b17baa85e6be9f54cf82b0e96e4f8c9f9a1",
      "exists": true,
      "gid": 0,
      "gr_name": "root",
      "isreg": true,
      "mode": "0644",
      "mtime": 1778020738.4909694,
      "path": "/etc/hostname",
      "pw_name": "root",
      "size": 9,
      "uid": 0
  }
}

Illustrative output

The common keys

Some keys are conventional across every module. Learn these and you can read any module’s output.

Key	Type	Meaning
`changed`	bool	The module claims it altered the target. Always present.
`failed`	bool	The module claims the task failed. Absent means false.
`msg`	str	A human-readable message, usually the reason for a failure.
`skipped`	bool	The task was not run — a false `when`, or check mode with no support.
`rc`	int	Exit status of a process the module ran, where one applies.
`stdout` / `stderr`	str	Captured output, where a process was run.
`stdout_lines` / `stderr_lines`	list	The same, pre-split on newlines.
`results`	list	One result per item, when the task used a loop.
`diff`	dict	Before and after content, shown with `--diff`.
`warnings` / `deprecations`	list	Surfaced by the callback, not usually consumed.

Everything else is module-specific and documented in that module’s RETURN VALUES section — stat for ansible.builtin.stat, ping for ansible.builtin.ping, ansible_facts for ansible.builtin.setup.

Read-only / Safethe module tells you its own return keys— Prints the documented return values for a module, with types and when each is returned. This is the section to read before writing a when: that depends on a registered result.

$ ansible-doc ansible.builtin.command | sed -n '/RETURN VALUES/,$p'

RETURN VALUES:

 cmd     The command executed by the task.
      returned: always
      sample: [echo, hello]
      type: list

 delta   The command execution delta time.
      returned: always
      sample: '0:00:00.001529'
      type: str

 rc      The command return code (0 means success).
      returned: always
      sample: 0
      type: int

 stdout  The command standard output.
      returned: always
      type: str

Illustrative output

The output above is trimmed: command also documents end, msg, start, stderr, stdout_lines and stderr_lines. Read the whole section rather than this excerpt when you are writing against it.

`stdout_lines` is not a convenience, it is the correct one

Given stdout and stdout_lines, use stdout_lines. Splitting a string in Jinja works until a line contains something you did not anticipate, and the module already did the split correctly on the target where the line endings came from.

Why `changed` is load-bearing

changed looks like reporting. It is control flow.

Handlers depend on it. notify fires when the notifying task reported changed: true. A task that always claims a change restarts your services on every run, forever.

Check mode depends on it. In --check, a module reports the changed it would have produced. If it cannot tell, --check cannot tell you either.

Conditionals depend on it. when: previous_task is changed is a common and correct pattern that becomes meaningless against a task that always claims a change.

Your evidence depends on it. “This run changed 3 hosts out of 300” is the sentence that makes a scheduled run reviewable. Against tasks that always claim a change it reads “this run changed 300 hosts out of 300”, every night, and nobody looks at it after week two.

`command` cannot know, so it always claims a change

Watch this. id -un reads a username and alters nothing:

$ ansible localhost -a "id -un"
localhost | CHANGED | rc=0 >>
opsuser

CHANGED. The module ran a process, the process exited 0, and command has no idea whether the process did anything, so it reports a change on principle.

This is not a bug and it is not fixable inside command. A module that runs an arbitrary program cannot inspect that program’s effect. It is the structural reason command and shell break idempotency, and it is why the fix is creates, removes, or changed_when — all of which are you supplying the knowledge the module cannot have.

What actually runs on the target

Ansible does not install anything. For each task it builds a self-contained Python zip archive — the AnsiballZ wrapper — containing the module source, the module_utils it imports, and your arguments serialised as JSON. That archive is copied to a temporary directory on the target, executed with the target’s Python, and deleted.

The module reads its arguments from that embedded JSON, does its work, prints a JSON document to stdout and exits. The controller parses stdout and that parsed document is the task result.

Three consequences follow directly:

Anything a module prints to stdout that is not the JSON document corrupts the result. A stray print() in a custom module produces “MODULE FAILURE” errors that look like a connection problem.
The module needs a Python on the target to run at all, which is why raw exists as the one module that does not.
The module runs with no access to your controller. It cannot read a file from your workstation. That restriction is real for genuine modules and is exactly what action plugins exist to work around — a distinction with its own lesson later in this part.

Two version-specific changes worth knowing

ansible-core 2.21 tightens the contract in two places. Both are the kind of detail that turns into a confusing afternoon if you learned Ansible on an older release.

`invocation` is no longer returned by default

Historically every module result carried an invocation key recording the arguments it was called with. In 2.21 that is opt-in, controlled by a new setting:

Read-only / Safethe new setting, and its default— Shows the resolved value of the setting that controls whether module results carry an invocation record. It is off unless you turn it on.

$ ansible-config dump | grep INJECT_INVOCATION

INJECT_INVOCATION(default) = False

So a registered result contains only what the module returned. This play asks the result what keys it has:

# keys.yml
- name: What keys does a module actually return
  hosts: localhost
  gather_facts: false
  tasks:
    - name: Stat a file
      ansible.builtin.stat:
        path: /etc/hostname
      register: h

    - name: List the top-level keys of the result
      ansible.builtin.debug:
        var: h.keys() | list

Read-only / Safedefault: no invocation key— Registers a stat result and prints its top-level keys. Three keys, and invocation is not among them.

$ ansible-playbook keys.yml

TASK [List the top-level keys of the result] ***********************************
ok: [localhost] => {
  "h.keys() | list": [
      "changed",
      "failed",
      "stat"
  ]
}

Turn it on when you need to see exactly what a module was called with — which is the single most useful thing when a templated argument did not resolve to what you assumed:

Read-only / Safeopt in for one run— Enables the invocation record for a single run. The result now carries the fully-resolved module arguments, including defaults you did not set.

$ ANSIBLE_INJECT_INVOCATION=1 ansible-playbook keys.yml

TASK [List the top-level keys of the result] ***********************************
ok: [localhost] => {
  "h.keys() | list": [
      "changed",
      "failed",
      "stat",
      "invocation"
  ]
}

Note that most callbacks still hide invocation from the screen below -vvv even when it is present. Registering the result and printing it is the reliable way to see it.

Failure inference from `rc` is deprecated

Historically, a module or action that returned a non-zero rc and no explicit failed value was inferred to have failed. The 2.21 porting guide deprecates that inference:

Failure inference for modules and actions that return a non-zero rc value and no failed value is deprecated. Modules and actions may use any logic desired to determine failure (including consulting rc), but failures must be explicitly communicated in the task result by setting failed true.

Runtime deprecation warnings arrive in 2.22, and when the inference is removed, rc receives no special treatment during result processing.

The direction of travel is the point of this lesson restated by upstream: the module must say whether it failed. Ansible is getting out of the business of guessing from a side channel.

What happens if a module succeeds on the target but reports failure?

You get a task marked failed, a play that may have stopped, and a change that landed anyway.

It happens for real reasons. A module completes its work and then fails while gathering the state it wants to return. A module runs a helper whose exit status does not mean what the module assumed. A module times out after the operation committed on the target.

The diagnosis is to distrust the report and go and look. Read msg and stderr — they usually name the step that failed, and if that step is after the change, the change happened. Then verify on the target with a read-only module.

The recovery is the reason idempotency matters so much. If the task was written with a purpose-built module, rerunning it is safe: the second run finds the state already correct, reports changed: false, and either succeeds or fails the same way, which tells you which of the two it is. If the task was a shell line, rerunning it does the work twice, and whether that is harmless depends entirely on what the command was.

The contract

The return value

The common keys

stdout_lines is not a convenience, it is the correct one

Why changed is load-bearing

Two version-specific changes worth knowing

invocation is no longer returned by default

Failure inference from rc is deprecated

Knowledge check

`stdout_lines` is not a convenience, it is the correct one

Why `changed` is load-bearing

`invocation` is no longer returned by default

Failure inference from `rc` is deprecated