Ansible has no undo · Ansible

Ansible provides no universal automatic rollback. There is no transaction wrapping a play, no snapshot taken before it runs, no journal of the previous state, and no --rollback flag. Nothing in ansible-doc, nothing in ansible-config list, nothing planned.

This part opens with that sentence because the alternative belief is common, load-bearing, and discovered to be false at the worst possible moment. The belief sounds like this:

Rollback is easy. It is all in git. If the change goes wrong we revert the commit and re-run.

That sentence gets written into change plans. It gets accepted by change boards. And during an incident, at 02:40, someone runs it and finds that about sixty per cent of the change came back and the rest did not.

What re-running an older revision actually does

It is worth being precise, because “git revert does nothing” would be just as wrong as the belief this lesson is correcting.

A role describes desired state. Running the previous revision of that role converges the hosts toward the state that revision declares. For a large class of changes that genuinely is a rollback:

A line in a config file changed from 4 to 16. The old role says 4. Re-running it writes 4. Correct.
A template gained a new stanza. The old template does not have it. Re-rendering writes the file without it. Correct.
A systemd unit gained Restart=always. The old unit file does not. Re-applying it plus daemon_reload restores the old behaviour. Correct.

Every one of those works because the role declares the full content of the thing it manages, so re-declaring the old content is sufficient.

Where it stops working

The failure is structural, not a bug, and it has three shapes.

1. State the new revision created that the old revision never mentions

This is the big one, and it is invisible in a diff review because the diff only shows what was added.

# The change: v2 of the role added these three tasks.
- name: Create the service account the new component runs as
  ansible.builtin.user:
    name: appmetrics
    system: true
    state: present

- name: Install the new agent
  ansible.builtin.apt:
    name: metrics-agent
    state: present

- name: Run the schema migration
  ansible.builtin.command: /opt/app/bin/migrate --to 47
  args:
    creates: /opt/app/.migrated-47

Revert the commit. The old role does not contain those tasks. It therefore does not say state: absent for the user, does not say state: absent for the package, and has no concept of migration 47 at all. Re-running it leaves:

the appmetrics user, still present, still in /etc/passwd
metrics-agent, still installed, still enabled, possibly still running
the database at schema 47, which the old application binary cannot read

The role reported ok on every task. The recap is green. The estate is not back.

2. Changes the platform cannot reverse

Some things are gone.

Change	Reversible by re-running the old role?	What it actually takes
Config value edited	Yes	Re-render the template
Package upgraded	Sometimes	An explicit version pin plus downgrade support
Package removed	Partly	Reinstall restores the binary, not the purged config
Kernel upgraded	No	Boot the previous entry, then remove the new one
Schema migrated forward	No	A down-migration, if one was written
Row deleted	No	Restore from backup
Filesystem reformatted	No	Restore from backup
Secret rotated at the provider	No	Rotate again to a third value

The right-hand column is the honest one. Notice how much of it says “restore from backup” — which is why the backup lesson in this part is not an appendix.

3. Downgrade paths that are not supported

ansible.builtin.apt and ansible.builtin.dnf both take an allow_downgrade option, and both document the same warning: setting it true “can make this module behave in a non-idempotent way”, because dependency resolution during a downgrade can drag other packages with it.

Service impact possiblea downgrade is a change, not an undo— Verified present in ansible-core 2.21.3 via ansible-doc. The apt option is aliased as allow_downgrades and allow-downgrade.

- name: Pin back to the previous application version
ansible.builtin.apt:
  name: acme-app=2.4.1-1
  state: present
  allow_downgrade: true

Even where the module supports it, three things stand between that task and a rollback:

The old version must still be in a repository you can reach. Many internal repositories keep only the current release. A vendor may have pulled the artefact.
The package may not support being downgraded. Post-install scripts frequently migrate on-disk data forward and have no reverse.
Dependency resolution may take other packages with it, which is precisely what the module documentation warns about.

`block`/`rescue` is compensation, not a transaction

The nearest thing Ansible offers to automatic recovery looks like this:

- name: Deploy with a compensating action
  block:
    - name: Swap the symlink to the new release
      ansible.builtin.file:
        src: /opt/app/releases/2.5.0
        dest: /opt/app/current
        state: link

    - name: Confirm the application answers
      ansible.builtin.uri:
        url: http://localhost:8080/healthz
        status_code: 200

  rescue:
    - name: Swap the symlink back
      ansible.builtin.file:
        src: "{{ previous_release_path }}"
        dest: /opt/app/current
        state: link

That is a real and useful pattern, and this part uses it. But read what it is: a second set of tasks that you wrote, that you have to keep correct, and that only runs if a task inside the block fails.

It is not a transaction, and the differences matter:

It does not run if the play succeeds but the outcome is wrong. A deploy that returns HTTP 200 from a broken build never enters rescue.
It does not run if the controller dies, the SSH session drops, or the operator presses Ctrl-C.
It does not know what the block changed. It only knows what you told it to undo. Anything the block changed that rescue does not mention stays changed.
On a host where the block half-completed, rescue runs with the host in a state neither branch was written for.

Why there is no undo, mechanically

The absence is not an oversight. It falls out of the execution model.

A module receives arguments, decides what to do on the target, does it, and returns a result dictionary. The controller sees the return value. It does not see — and has no general way to see — what the module touched. apt may have run a hundred maintainer scripts. command ran an arbitrary program. There is no per-task manifest of side effects, because there is no mechanism that could produce one for shell.

For a transaction you would need three things Ansible does not have:

A complete record of prior state for everything a task might touch. Only the target knows this, and only some of it (copy knows the old file; nothing knows what a command overwrote).
A reverse operation for every module. Some have none — command, shell, raw, script are arbitrary code.
Atomicity across hosts. Ansible fans out to hundreds of machines over independent SSH connections. There is no coordinator that can roll all of them back to a consistent point, because there is no consistent point.

The declarative model gives you convergence — run it again and the state matches the declaration. Convergence is a strong property and it is not reversibility. Convergence says “the future will match what I declare”. Reversibility would require knowing the past, which nothing recorded.

This is why backup: true exists on copy and template: those two modules do know the prior state of the one file they manage, so they can be asked to keep a copy of it. The scope of that option is exactly the scope of what the model can offer.

The consequence for how changes are planned

If there is no automatic reverse, the reverse has to be built, and it has to be built before the change runs. That gives this part its structure:

Write the reverse first. Lesson 2. A change with no written reverse does not get a window.
Know which pattern applies. Lesson 3. Config file, package, kernel, service unit, snapshot — each answers a different failure and each costs a different amount.
Run the window as a controlled sequence. Lesson 4.
Expose progressively, with criteria that abort automatically. Lesson 5.
Take the backup, and restore one to prove it. Lesson 6.
Reconcile the fleet afterwards, because a partial rollback leaves more than one population. Lesson 7.

What happens if you revert the commit and re-run anyway?

Sometimes it is the right move, and this lesson is not an argument against it. It is an argument for knowing what it leaves.

Run it, and then answer these four questions explicitly rather than assuming the recap answered them:

What did the new revision create that the old one does not mention? Users, groups, packages, directories, cron entries, unit files, firewall rules, database objects. Diff the two revisions and read only the additions — every added state: present is a candidate.
What did the change do outside Ansible? Migrations, provider-side secret rotations, DNS records, load-balancer registrations.
What data was written by the application while the new version was live? Reverting the code does not revert the rows.
What is now version-skewed? If half the fleet reverted and half did not, you have two populations, and lesson 7 is about that.

Write the answers down before running the revert, not after. During an incident nobody enumerates carefully.

Knowledge check

Why this matters

The cost of this misunderstanding is paid entirely during incidents, which is the worst time to discover an assumption was wrong.

A change plan that says “rollback: revert and re-run” passes review because it sounds like it describes a procedure. It does not describe a procedure — it describes a mechanism and assumes the procedure follows. Nobody on the review has to think about the created user or the migrated schema, because the sentence did not raise them.

Then the change goes wrong, the revert runs, the recap is green, and the next twenty minutes are spent trying to work out why the application is still broken when the rollback succeeded. That is twenty minutes of an outage spent on a question that a five-line reverse procedure would have answered before the window opened.

The rest of this part is about writing those five lines. But the whole part depends on accepting the first sentence: there is no undo, and anything that looks like one is something a person built.