What deploy means to a convergent tool · Ansible

“Deploy” is a word borrowed from tools that do not work the way Ansible works, and the borrowing causes real problems.

To a deployment tool built around artefacts and releases, a deploy is an event: version 4.2 replaces version 4.1 at 14:07, atomically, with a before and an after. To Ansible, a deploy is a convergence: the host is brought to a described state, and if it is already in that state nothing happens.

Those are different enough that a role written with the first model in mind and executed by the second produces the characteristic failure of this part — a deployment that works the first time and is a gamble every time after.

The unit is a state, not a sequence

A deployable unit in this course is four things converged together:

Component	Converged by	The question it answers
Package or artefact	`apt`, `dnf`, `get_url`, `unarchive`	which version of the code is on disk
Configuration	`template`, `copy`	what the code is told to do
Service	`systemd_service`	whether it is running and enabled
Validation	`uri`, `assert`, `command`	whether it is actually working

All four, in one role, converged in one run. Not a package role and a config role and a “deploy” playbook someone runs afterwards — because the moment they are separate, there is a window in which the host has the new code and the old configuration, and somebody will find that window.

Service impact possiblethe shape of a deployable unit— Installs a pinned version, writes validated configuration, ensures the service state, and refuses to finish until the service reports the version that was deployed. Rerunning it against a converged host changes nothing.

- name: Install the pinned application version
ansible.builtin.apt:
  name: 'myapp={{ myapp_version }}'
  state: present
notify: Restart myapp

- name: Write the application configuration
ansible.builtin.template:
  src: myapp.conf.j2
  dest: /etc/myapp/myapp.conf
  owner: myapp
  group: myapp
  mode: '0640'
  backup: true
  validate: '/usr/bin/myapp --check-config %s'
notify: Restart myapp

- name: Ensure the service is enabled and running
ansible.builtin.systemd_service:
  name: myapp
  state: started
  enabled: true

- name: Apply any pending restart before validating
ansible.builtin.meta: flush_handlers

- name: Prove the deployed version is the version serving
ansible.builtin.uri:
  url: 'http://{{ ansible_host | default(inventory_hostname) }}:8080/healthz'
  return_content: true
register: health
retries: 20
delay: 3
until: health.json.version | default('') == myapp_version
changed_when: false

Run that against a host already at myapp_version and every task reports ok, no handler fires, and the validation confirms what was already true. Run it against a host at the previous version and it converges. Run it against a host where the previous run died halfway and it finishes the job.

That last property is the one worth paying for.

Rerun safety is what makes a partial run recoverable

Consider a deployment role of twelve tasks where task seven is not rerun-safe — it appends to a file, or it runs a command that assumes the previous version is present.

The first run works. Nothing is wrong. The problem only appears the first time a run does not complete: a connection drops at task nine, a max_fail_percentage stops the play, somebody presses Ctrl-C.

Now the host is in a state where tasks one to eight have been applied. The obvious recovery — run it again — re-executes task seven, and task seven is the one that cannot survive that.

Service impact possiblethe task that quietly breaks rerun safety— Appends to a file on every execution. Correct once, and cumulative thereafter — the second run produces a file with the block twice.

# Not rerun-safe: appends unconditionally.
- name: Add the application to the startup script
ansible.builtin.shell: |
  echo "/opt/myapp/bin/start" >> /etc/rc.local

Configuration changethe same intent, converged— Declares the desired content of a managed region. The second run finds the region already correct and reports ok.

- name: Manage the application startup entry
ansible.builtin.blockinfile:
  path: /etc/rc.local
  marker: '# {mark} ANSIBLE MANAGED: myapp'
  block: |
    /opt/myapp/bin/start
  create: false

The second version is not merely tidier. It is the difference between a role you can rerun and a role you cannot.

What Ansible converges and what it merely performs

Being honest about this line is what stops the model becoming a superstition.

Converged — the module inspects the current state and acts only if it differs. apt, dnf, template, copy, file, systemd_service, user, lineinfile, blockinfile. These report changed truthfully and are safe to rerun by construction.

Performed — the module runs a thing. command, shell, script, raw. Ansible has no idea what they do, cannot tell whether they have already been done, and reports changed by default because it must assume the worst.

Ambiguous — modules whose idempotence depends on how you call them. get_url is converged when the destination exists and matches the checksum, and a fresh download otherwise. unarchive is converged only if you give it creates.

Configuration changemaking a performed step behave like a converged one— Runs the migration binary only when its sentinel file is absent. creates makes the task a no-op on a host where the step has already been done, which is what makes the role rerunnable.

- name: Run the one-time data migration for this release
ansible.builtin.command:
  argv: [/opt/myapp/bin/migrate, '--to', '{{ myapp_version }}']
  creates: '/var/lib/myapp/.migrated-{{ myapp_version }}'

creates is the cheapest idempotence available for a command task: when the named path exists, the task is skipped entirely. The requirement is that the command itself creates that path — which means the sentinel must be written by the migration, not by a following file task, or a migration that fails halfway leaves a sentinel saying it succeeded.

Where the convergence model genuinely does not fit

Three parts of a deployment resist it, and pretending otherwise is worse than acknowledging it.

Schema migrations. Applying a migration twice is not idempotent in the way a file is; the second application either errors or does damage. Migration frameworks maintain their own state table for exactly this reason. Ansible’s job is to invoke the framework, not to reimplement it. This gets a whole lesson later in this part.

Anything with an external side effect. Sending a deployment notification, incrementing a release counter, posting to a chat channel. Rerunning duplicates it. These are usually harmless and should be recognised as performed rather than converged.

Traffic cut-over. Ansible can tell a load balancer to change a backend’s state, and that call is idempotent. What it cannot do is make the cut-over atomic across the fleet, and that limit is the subject of the last lesson in this part.

Under the hood

What “converged” actually means in module terms is worth pinning down, because changed is not a judgement — it is a return value.

Every module returns a dictionary containing changed. The module decides it. ansible.builtin.template renders the template on the controller, computes a checksum, compares it against the checksum of the file on the host, and returns changed: false when they match — writing nothing. ansible.builtin.systemd_service queries the unit’s current active state and returns changed: false if it already matches the requested state.

ansible.builtin.command has no equivalent inspection available. It returns changed: true on any successful execution, because the only honest answer to “did that change anything” is “I have no idea”, and true is the safer default. That default is what makes an unguarded command in a deployment role produce a permanently yellow run.

This is why handler notification and change detection are the same mechanism. A handler fires when a task returns changed: true. A deployment role built on converged modules therefore restarts the service exactly when something that warrants a restart happened — and a role sprinkled with command tasks restarts it on every run, because every run is changed.

The changed_when: false that people reach for to fix the yellow does fix the yellow. It also detaches the handler from reality: the task now never notifies, so a command that did change something no longer triggers the restart it should have. Both failure directions come from the same place, which is a command task standing in for a module that would have known the answer.

What happens if the deployment role is run against a host that has drifted?

It converges the drift away, which is usually right and occasionally catastrophic, and the difference is whether anyone knew the drift was there.

The good case: someone edited /etc/myapp/myapp.conf by hand during an incident three weeks ago to work around a bug. The next deployment run replaces it from the template, the workaround disappears, and the service returns to the state the repository describes. That is the system working. The workaround should have been made permanent in the template or explicitly reverted; instead it survived undocumented until a routine run removed it.

The bad case is the same events with a different workaround — one that was load-bearing, whose removal takes the service down, in a run that nobody was watching because it was routine.

Two things reduce the gap between them. backup: true on template and copy leaves the previous file on the host with a timestamp, which turns “what did we just overwrite” from an archaeological question into a diff. And a check-mode run before the real one shows the drift before it is removed: --check --diff across the fleet lists every host whose configuration differs from the repository, which is the drift report the configuration-management parts of this course argue for.

The deeper point is that a deployment role is a drift-remediation role whether you designed it as one or not. Every run asserts the whole described state, not just the part that changed in this release.

Knowledge check

Why this matters

Every other lesson in this part assumes the model this one describes.

Health gates are worth writing because a converged role can be rerun after one fails. Version pinning is meaningful because the version is a described state rather than a command that happened to run. Rolling deploys through a load balancer work because a batch that fails can be repaired and the play rerun without redoing the batches that succeeded.

The alternative model — a deploy as a sequence of steps that happened at a point in time — produces roles that work in a demonstration and degrade in production, because production is where runs get interrupted.

The test is a single question, and it is worth asking of every task you add to a deployment role: if this run stops here, is running it again the correct recovery?

Where the answer is yes for every task, the operational procedure for every failure in the entire role is three words. Where it is no for even one, there is no procedure at all — only whatever the person on call works out at the time.