The Module Model

A module is the unit of work in Ansible — a small program that takes desired state as arguments, inspects the machine's current state, and makes only the changes needed to match. It is where idempotency physically lives: the apt module checks whether nginx is already installed before doing anything, and reports ok when there was nothing to do or changed when it acted, honestly. That honest reporting is what lets you run the same play every hour and have it settle after the first run.

There is no state file telling the module what it did last time. The managed node is the record, re-read live on every run. Everything in this topic follows from that one fact, and it is the spine the whole course turns on.

Desired State In, Result Out

A module is called with arguments describing the end state — name=nginx state=present — and returns a JSON result describing what it found and what it did. The module owns the logic of getting from current to desired, so you declare the destination and it computes the route. You never write the apt-get install step; you state that nginx should be present and let the module decide whether anything is needed.

This is the declarative core of Ansible in miniature. Two engineers can write the same task and mean exactly the same thing, because the task names an outcome, not a procedure. The procedure is the module's business, and it varies with what the machine already looks like.

The ok / changed / failed Contract

Every module reports one of three outcomes per host: ok means the machine was already in the desired state and nothing was done, changed means it altered the machine, and failed means it could not reach the desired state. The play's recap counts these, and the signal you want is plain — a correct play is all ok on its second run, because the first run already converged it.

Read the recap as a convergence signal, not noise. A green ok does not mean "Ansible did the work" — it means the work was already done. The line that acted is changed, and a persistent changed on every run is a footgun pointing at a module that is not actually idempotent.

Why changed Must Be Honest

The changed flag is not cosmetic. It is what fires handlers — reload nginx only when the config actually changed — what --check reports, and what tells you a "no-op" run was truly a no-op. The whole notification system that you will build in playbooks hangs off this one boolean being true exactly when something changed.

A module that reports changed when nothing changed poisons all of that. It reloads services needlessly, makes every run look unsettled, and trains you to ignore the very signal you should be reading. This is why the next topic draws such a hard line around command and shell, which cannot report changed honestly on their own.

Idempotency Is Per-Module, Against Live State

Each module reads the machine's real state every run and compares it to the declared arguments, which makes idempotency stronger than a stored snapshot that can quietly lie about reality. A file someone edited by hand is detected and re-converged, because the truth is on the disk Ansible just read, not in a state file written hours ago that the world has since moved past.

That live re-read is the safety net the no-state-file model gives you. Drift does not accumulate silently and surface during an incident — the next run finds it and corrects it, because the module always asks the machine directly rather than trusting a record of what was supposed to be true.

The Execution Mechanism

Concretely, Ansible generates the module code, copies it to the managed node over SSH into a temporary directory, runs it under the node's Python 3, captures the JSON it prints on stdout, and removes it. Nothing of Ansible stays behind on the host. That is the agentless model made physical: no daemon, no installed agent, just a small program copied in, run once, and cleaned up.

Because each run copies the module over fresh and deletes it after, there is no module state to persist between runs and none to corrupt. Each run re-reads the node from scratch. There is nothing to rely on across runs and, equally, nothing to break — the machine itself carries all the memory the system has.

Reading Return Values

Modules return structured data, and you capture it by registering a task's result. Alongside changed and failed, a module returns its own keys — stdout, dest, diff, and others specific to what it does. Later tasks branch on these values, so knowing a module's return shape is as important as knowing its arguments, and the next topics show where to read both.

Register the result and branch on what the module actually returned rather than hard-coding an assumption. If a later task needs to know whether a file changed, read the changed the copy module reported; do not re-derive it with a separate command that re-checks the disk and adds a second non-idempotent step.