Making "exactly once" actually mean once · Ansible

The previous lesson established that run_once means once per batch. This one is about what to write instead, and the useful move is to stop asking “how do I make run_once behave” and start asking what the task actually needs.

Three intents hide behind the same keyword:

“This work happens one time per run.” A schema migration. A release tag. A change-ticket transition.
“Only one host may do this at a time.” Anything competing for a shared lock, a licence seat, or an API rate limit.
“This is not about any host.” Fetching a manifest, validating input, notifying a channel.

Each has a construct that expresses it, and each construct survives serial because it does not depend on the batch.

Intent one: once per run

The play host lists are the tool, and choosing between them is the whole decision.

Read-only / Safethe three host lists under serial— Six hosts, serial: 2, verified on ansible-core 2.21.3. The task is a run_once debug, printed once per batch, so all three scopes are visible side by side.

$ ansible-playbook -i hosts.ini playhosts-serial.yml

"msg": "web1: play_hosts=['web1', 'web2', 'web3', 'web4', 'web5', 'web6'] batch=['web1', 'web2'] all=['web1', 'web2', 'web3', 'web4', 'web5', 'web6']"
"msg": "web3: play_hosts=['web1', 'web2', 'web3', 'web4', 'web5', 'web6'] batch=['web3', 'web4'] all=['web1', 'web2', 'web3', 'web4', 'web5', 'web6']"
"msg": "web5: play_hosts=['web1', 'web2', 'web3', 'web4', 'web5', 'web6'] batch=['web5', 'web6'] all=['web1', 'web2', 'web3', 'web4', 'web5', 'web6']"

Variable	Scope	Shrinks when a host fails?
`ansible_play_hosts_all`	every host the play started with	no
`ansible_play_hosts`	the whole play, active hosts only	yes
`ansible_play_batch`	the current `serial` batch, active hosts	yes

Only the third is batch-scoped, and that is precisely why run_once — which works in batch terms — repeats. A condition written against either of the first two is evaluated identically in every batch, so exactly one host in the whole play satisfies it.

Read-only / Safeonce per play, whatever serial says— A conditional, not a keyword. It is evaluated per host like any other when:, which is what makes it immune to the run_once host-loop bypass.

- name: Apply pending schema migrations
ansible.builtin.command: /opt/app/bin/migrate --apply
args:
  chdir: /opt/app
when: inventory_hostname == ansible_play_hosts[0]
delegate_to: "{{ migration_runner_host }}"

Verified with serial: 2 over six hosts: the task ran once, on web1, in the first batch, and was skipped for every host in batches two and three.

Note that this is a plain when: with no run_once anywhere. That is the point — the conditional is evaluated on every host individually, so none of the run_once hazards from the previous lesson apply. It composes with other conditions normally, and a reader can work out what it does without knowing the keyword’s edge cases.

Which list: `ansible_play_hosts` or `ansible_play_hosts_all`?

They differ in one situation, and it is the situation that matters: when the host they name has already dropped out.

Read-only / Safeweb1 fails, then both forms are tried— Six hosts, no serial. web1 is removed by an ansible.builtin.fail, which changes nothing. Verified on 2.21.3.

$ ansible-playbook -i hosts.ini allzero-fail.yml

TASK [web1 drops out] **********************************************************
fatal: [web1]: FAILED! => {"changed": false, "msg": "web1 is out"}
skipping: [web2]
skipping: [web3]
skipping: [web4]
skipping: [web5]
skipping: [web6]

TASK [Once per play via ansible_play_hosts_all[0]] *****************************
skipping: [web2]
skipping: [web3]
skipping: [web4]
skipping: [web5]
skipping: [web6]

TASK [Compare - ansible_play_hosts[0] instead] *********************************
ok: [web2] => {
  "msg": "PLAY_HOSTS[0] on web2 (hosts[0]=web2)"
}
skipping: [web3]
skipping: [web4]
skipping: [web5]
skipping: [web6]

ansible_play_hosts_all[0] is still web1. web1 is gone, so no surviving host matches and the task ran nowhere at all — silently, with a clean recap.

ansible_play_hosts[0] had already become web2, so the task ran.

Both behaviours are defensible and they encode different requirements:

ansible_play_hosts[0] — “this must happen once, on some host”. The default choice. Resilient, and the failure of one host does not silently cancel the shared work.
ansible_play_hosts_all[0] — “this must happen once, on a host chosen deterministically”. Stable across runs while the inventory is stable, and it stops rather than substituting when that host is unavailable.

If the answer is “it must happen once, on a specific host”, neither is right — that is delegate_to with a named host, and the condition is only deciding how often.

A skipped task is not a reported task

The ansible_play_hosts_all[0] case above produced a run with no failures, no warnings, and a schema migration that did not happen.

Whenever a shared, must-happen-once operation is gated by a condition, something afterwards has to confirm it happened. A conditional that silently evaluates false is the same shape as the run_once plus when: trap from the previous lesson, arrived at from the other direction.

- name: Apply pending schema migrations
  ansible.builtin.command: /opt/app/bin/migrate --apply
  args:
    chdir: /opt/app
  when: inventory_hostname == ansible_play_hosts[0]
  delegate_to: "{{ migration_runner_host }}"
  register: migration

- name: Refuse to deploy against an unmigrated schema
  ansible.builtin.command: /opt/app/bin/migrate --check-current
  changed_when: false
  delegate_to: "{{ migration_runner_host }}"
  run_once: true

The second task is not a duplicate of the first. It asks the system of record whether the state you require is true, which is a different question from whether your task ran. It is safe under run_once because checking three times is harmless — the property from the previous lesson’s checklist that lets you stop worrying.

Intent two: one at a time, but everyone

throttle is the keyword for “this task must not run concurrently”, and it is a different requirement from “this task must run once”.

The distinction is worth stating plainly, because teams reach for run_once when they mean throttle: 1: run_once means five hosts get the work done by one of them; throttle: 1 means all five do the work, one after another.

Read-only / Safethrottle measured— Four hosts, one task that waits two seconds, run four ways. wait_for with only a timeout sleeps and touches nothing. Verified on ansible-core 2.21.3.

$ /usr/bin/time -f 'elapsed %e s' ansible-playbook -i thr.ini thr.yml -f 5

-- forks 5, no throttle --
elapsed 2.48 s

-- forks 5, throttle 1 --
elapsed 8.91 s

-- forks 1, no throttle --
elapsed 8.92 s

-- forks 1, throttle 4 (cannot raise above forks) --
elapsed 8.91 s

Four hosts at two seconds each: 2.5 seconds in parallel, 8.9 seconds serialised. The last measurement is the one worth keeping — throttle: 4 with forks: 1 still took 8.9 seconds, because throttle can only lower concurrency, never raise it. The keyword documentation says so directly: “This is independent of the forks and serial settings, but cannot be set higher than those limits.”

Where this replaces a misused run_once:

Configuration changeevery host registers itself, one at a time— Each host must appear in the service registry, so every host runs the task. The registry API tolerates one writer at a time, so they take turns.

- name: Register this host with the service catalogue
ansible.builtin.uri:
  url: "https://catalogue.example.com/api/v1/nodes"
  method: POST
  body_format: json
  body:
    name: "{{ inventory_hostname }}"
    role: "{{ node_role }}"
  headers:
    Authorization: "Bearer {{ catalogue_token }}"
delegate_to: localhost
throttle: 1
no_log: true

Every host needs its own registration, so run_once would be wrong in the strongest sense — five of six hosts would go unregistered. throttle: 1 gets all six done without ever having two writers at the catalogue at once.

throttle applies to Play, Role, Block, Task and Handler, so a whole block of tasks that share one lock can be serialised together rather than task-by-task. The performance side of it — protecting package mirrors, licence servers and rate-limited APIs — is the subject of a lesson in the next part.

Intent three: not about any host

When the work is not per-host at all, the cleanest construct is the one that does not need a keyword: a play that targets one thing.

Read-only / Safeglobal work in its own play— Once by structure. There is no host loop to bypass, so there is nothing for serial to divide.

- name: Pre-flight
hosts: localhost
gather_facts: false
connection: local
tasks:
  - name: Fetch the release manifest
    ansible.builtin.uri:
      url: "https://artifacts.example.com/releases/{{ release_version }}.json"
      return_content: true
    register: manifest

  - name: Refuse to proceed without a signature
    ansible.builtin.assert:
      that:
        - manifest.json.signature is defined
      fail_msg: "Release {{ release_version }} is unsigned; aborting."

- name: Roll the web tier
hosts: web
serial: 4
tasks:
  - name: The actual rollout
    ansible.builtin.debug:
      msg: "deploying {{ hostvars['localhost']['manifest']['json']['version'] }}"

Three properties make this the strongest of the three constructs where it fits:

Once is structural. No keyword to misread, nothing for a future serial: to change.
It fails before anything is touched. An unsigned manifest stops the run while the fleet is untouched, which is a better place to stop than batch two of five.
The value is available to every host, through hostvars['localhost'], and it is the same value for all of them — unlike a run_once registration, which differs per batch.

The cost is that variables do not flow implicitly between plays. Reaching back through hostvars['localhost'] is the price, and it is a fair one for work that genuinely belongs to the run rather than to a host.

Choosing, in one table

What you mean	Write
Once per run, on some surviving host	`when: inventory_hostname == ansible_play_hosts[0]`
Once per run, on a deterministic host, or not at all	`when: inventory_hostname == ansible_play_hosts_all[0]`
Once per run, on one named host	`delegate_to: <host>` plus one of the conditions above
Every host, but never two at once	`throttle: 1`
Not about any host	a separate `hosts: localhost` play
Once per batch, deliberately	`run_once: true` — and say why in a comment

The last row is not a joke. run_once is correct when the work genuinely is per-batch: refreshing a fact about a shared dependency at the start of each batch, or logging batch boundaries. Write the comment, because the next reader will assume you meant once per play.

Under the hood

Why does a condition on ansible_play_hosts[0] behave differently from run_once, when both seem to be selecting one host?

Because they act at different points. run_once bypasses the host loop — the definition says so — and the loop is what serial divides into batches. Bypassing it means the task is scheduled once for whatever collection of hosts is currently being processed, and under serial that collection is a batch.

A when: does not bypass anything. The host loop runs in full, the condition is evaluated independently for every host, and exactly one evaluation is true because the list it compares against is play-scoped rather than batch-scoped. Batching becomes irrelevant, because the condition never asks about the batch.

That also explains the second-order differences observed in the previous lesson, none of which apply to the conditional form:

Facts do not propagate. A set_fact under the conditional sets the fact on that one host only. Under run_once it lands on every active host in the batch. If you need the value elsewhere, read it with hostvars[ansible_play_hosts[0]], which is explicit and works across batches.
A failure fails one host. Under run_once, a failure is applied to every active host in the batch and stops all of them. Under the conditional, only the host that ran it fails, and the rest of the play continues — which is either what you want or a reason to add any_errors_fatal, depending on whether the shared work was a precondition.

Neither behaviour is better in general. They are different, and the difference is invisible unless you know where the host loop was bypassed.

What happens if the play targets a single host and you use these constructs anyway?

They all still work, and they all still cost nothing.

With one host in the play, ansible_play_hosts[0] is that host, so the condition is always true. throttle: 1 bounds concurrency that was already

run_once runs once, because there is one batch containing one host.

That is worth knowing for a specific reason: the single-host case is where these constructs get written and tested, and it is the case that cannot distinguish them. A developer working against one test VM sees identical behaviour from all four options and picks whichever reads best. The difference appears the first time the play is aimed at a real group, which is usually production.

If you have a habit worth forming from this part, it is to test multi-host behaviour on a multi-host inventory before the change reaches anything that matters — even a throwaway inventory of six unreachable documentation addresses will reveal how many times a task is scheduled, because the scheduling happens before the connection.

Intent one: once per run

Which list: ansible_play_hosts or ansible_play_hosts_all?

Intent two: one at a time, but everyone

Intent three: not about any host

Knowledge check

Which list: `ansible_play_hosts` or `ansible_play_hosts_all`?