In Ansible, what does a module reporting "changed" actually mean, and why do the command and shell modules report changed on every run?

## What "changed" is a promise about Ansible's execution model is a sequence of tasks, each dispatching one module to the managed host. The module's job is not "run this action" but "make this statement true". A well-behaved module therefore does four things in order: gather the current state of the thing it manages, compare that with the parameters the task declared, take action only if they differ, and return JSON that includes a `changed` boolean reflecting whether it acted. That boolean is load-bearing in three places. It drives the per-host recap counters (`ok`, `changed`, `failed`), it decides whether a `notify` fires its handler, and it is the signal humans use to answer "did this run do anything to production?". A run that is entirely `ok` is the proof that the hosts already match the playbook — Ansible's version of convergence. ```yaml - name: Ensure nginx is installed ansible.builtin.package: name: nginx state: present ``` Run this on a host that already has nginx and the package module queries the package database, sees no work to do, and returns `changed: false`. That is the contract being honoured. ## Why command and shell cannot honour it `ansible.builtin.command` and `ansible.builtin.shell` take a command line and execute it. Ansible has no model of what `/usr/local/bin/bootstrap.sh` or `sed -i ...` does, no way to inspect the state before, and no way to diff it after. A non-zero exit is a failure; a zero exit could mean "I did the work" or "there was nothing to do" and the module cannot distinguish them. It therefore reports `changed: true` on every successful run — the conservative choice, since under-reporting a change would silently suppress handlers. The same applies to `ansible.builtin.raw` (which does not even require Python on the target) and to any module you write badly. It is not a bug in command; it is the absence of information. ## Constraining a shell-out In preference order: **1. Use the purpose-built module.** Most shelling-out is a habit, not a necessity. `sed -i` on a config file is `ansible.builtin.lineinfile` or, better, a whole-file `ansible.builtin.template`. `curl` against an API is `ansible.builtin.uri`. `git clone` is `ansible.builtin.git`. `systemctl enable --now` is `ansible.builtin.service` or `ansible.builtin.systemd_service`. These modules already do the state comparison for you and support check mode. **2. Guard with `creates` or `removes`.** Both `command` and `shell` accept a `creates` path (skip the task if that path already exists) and a `removes` path (skip if it does not exist). The task then reports `skipped` on subsequent runs. This makes the task idempotent at the task level even though the command itself is not — it is the standard pattern for one-shot installers and migrations that drop a marker file. ```yaml - name: Bootstrap the application once ansible.builtin.command: cmd: /usr/local/bin/bootstrap.sh creates: /var/lib/app/.bootstrapped ``` **3. Set `changed_when` explicitly.** For a command that only reads (`ansible.builtin.command: /usr/bin/systemctl is-active nginx`), `changed_when: false` tells Ansible the task never changes anything. For a command whose output reveals whether it acted, register the result and derive `changed_when` from it. This is the escape hatch when `creates` does not fit. A fourth, occasionally correct answer: if the operation is repeated across many roles and deserves a real state comparison, promote it into a custom module. ## Check mode makes the cost visible Running with `--check` asks every module to predict its change without making it. Modules that implement check mode return the `changed` they would have produced. `command` and `shell` skip entirely in check mode by default, because running an arbitrary command is exactly what check mode promised not to do. So a playbook heavy in shell tasks produces a `--check` run that reports almost nothing and predicts almost nothing — the dry run stops being a dry run and becomes a blank page. Setting `check_mode: false` on a genuinely read-only command task is how you get such a task to run during a check. ## Why interviewers care A playbook full of always-changed tasks is one you cannot run continuously, cannot diff, and cannot trust. Handlers fire on every run, so services restart during an unrelated deploy. The recap is always noisy, so nobody reads it, so a real change hides in the noise. And the playbook stops being a description of desired state and turns back into a shell script written in YAML — which is precisely the thing configuration management exists to replace. A note on naming: the fully-qualified names shown here (`ansible.builtin.command`) are the collection-era spelling introduced with ansible-core 2.10; the short names `command` and `shell` still resolve and appear in older playbooks.