run_once means once per batch · Ansible

Almost everyone who uses run_once believes it means “run this task one time for this play”. It does not, and the difference only appears once you add serial — which you add later, for safety, in a change that looks entirely unrelated.

This lesson is short on opinion and long on evidence, because this is a semantic people state confidently and get wrong, and anything that mutates shared state depends on it.

What the keyword actually says

Not from memory, and not from a blog post. From the installed controller:

Read-only / Safethe definition on your own controller— ansible-doc reads the installed ansible-core. This is 2.21.3 and it is the definition your runs are using.

$ ansible-doc -t keyword run_once

run_once:
applies_to:
- Play
- Role
- Block
- Task
- Handler
description: Boolean that will bypass the host loop, forcing the task to attempt
  to execute on the first host available and afterward apply any results and facts
  to all active hosts in the same batch.
priority: 0
template: explicit
type: bool

Three phrases in that sentence carry the whole behaviour, and each one is a separate surprise:

“the first host available” — not a host you chose, and not necessarily the same host on the next run.
“all active hosts in the same batch” — batch, not play. If you have serial, you have batches.
“apply any results and facts” — the outcome of the task, including a failure, is written onto every other host in that batch.

Once per batch, demonstrated

Six hosts, serial: 2, one task marked run_once:

- name: run_once under serial
  hosts: web
  gather_facts: false
  serial: 2
  tasks:
    - name: This claims to run once
      ansible.builtin.debug:
        msg: "RUNONCE executed on {{ inventory_hostname }} | batch={{ ansible_play_batch }} | all={{ ansible_play_hosts_all }}"
      run_once: true

Read-only / Safethree executions, not one— Verified on ansible-core 2.21.3. All six hosts use ansible_connection=local and the only task is a debug, so nothing was changed anywhere.

$ ansible-playbook -i hosts.ini runonce.yml

PLAY [run_once under serial] ***************************************************

TASK [This claims to run once] *************************************************
ok: [web1] => {
  "msg": "RUNONCE executed on web1 | batch=['web1', 'web2'] | all=['web1', 'web2', 'web3', 'web4', 'web5', 'web6']"
}

PLAY [run_once under serial] ***************************************************

TASK [This claims to run once] *************************************************
ok: [web3] => {
  "msg": "RUNONCE executed on web3 | batch=['web3', 'web4'] | all=['web1', 'web2', 'web3', 'web4', 'web5', 'web6']"
}

PLAY [run_once under serial] ***************************************************

TASK [This claims to run once] *************************************************
ok: [web5] => {
  "msg": "RUNONCE executed on web5 | batch=['web5', 'web6'] | all=['web1', 'web2', 'web3', 'web4', 'web5', 'web6']"
}

PLAY RECAP *********************************************************************
web1                       : ok=1    changed=0    unreachable=0    failed=0
web3                       : ok=1    changed=0    unreachable=0    failed=0
web5                       : ok=1    changed=0    unreachable=0    failed=0

Three executions. On web1, web3 and web5 — the first host of each batch.

The two special variables in that output are the tools for reasoning about it, and they behave differently:

ansible_play_batch is the current batch. It changed on every iteration.
ansible_play_hosts_all is the whole play’s host list. It was identical in all three, unaffected by batching.

That second variable is what lesson 6 builds the fix from.

The break/fix this produces

A team runs database migrations from the play that deploys the application:

- name: Apply pending schema migrations
  ansible.builtin.command: /opt/app/bin/migrate --apply
  args:
    chdir: /opt/app
  run_once: true
  delegate_to: "{{ groups['appservers'] | first }}"

It worked for a year. Then, after an incident, somebody added serial: 5 to the play — a good change, made for good reasons, in a commit whose message says “stage the rollout”.

The next release ran the migration three times. The first application succeeded. The second was a no-op because the migration tool tracks applied versions. The third hit a partially-applied migration mid-write and failed on a duplicate key, leaving the schema in a state the tool could not resume from.

Nothing about the migration task changed. Nothing in the diff mentions run_once. The reviewer who approved serial: 5 had no reason to think about it, and the person who wrote run_once a year earlier had no serial to think about.

Any task that mutates shared state and relies on run_once is one serial: line away from running N times. That is the sentence to remember from this lesson.

“The first host available” is not a fixed host

The second phrase in the definition has its own consequences. run_once does not pick a host and stick with it — it takes whichever host is first in the current batch and still active.

Six hosts, no serial, with web1 failing in an earlier task:

Read-only / Safethe first host is gone, so the next one runs it— Verified on 2.21.3. The failing task is ansible.builtin.fail, which changes nothing; it exists to remove web1 from the play.

$ ansible-playbook -i hosts.ini runonce-hostgone.yml

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

TASK [Which host does run_once pick now] ***************************************
ok: [web2] => {
  "msg": "RUNONCE on web2"
}

The task ran on web2. That is correct behaviour and it is exactly what “first host available” means — but it has an operational edge that is easy to miss.

If the run_once task depends on something about the host it runs on — a mounted filesystem, a database client configuration, a firewall rule permitting egress, a credential in a local file — then it worked on web1 during testing and will now attempt to run on whichever host happens to survive. Two runs of the same playbook can execute the same task on two different machines with no change to the playbook at all.

The fix is not to make every host identical. It is to stop letting the scheduler choose: name the host with delegate_to, so the task runs where you decided it should.

A `when:` on a `run_once` task is evaluated once

This is the sharpest edge in the lesson, because the failure is total silence.

run_once bypasses the host loop before the conditional is evaluated. The when: is therefore tested against one host only — the first available one — and its result decides the task for the entire batch.

- name: Only web4 satisfies the condition
  ansible.builtin.debug:
    msg: "RUNONCE+WHEN on {{ inventory_hostname }}"
  run_once: true
  when: inventory_hostname == 'web4'

Read-only / Safethe task that never runs anywhere— Six hosts, no serial. Verified on 2.21.3.

$ ansible-playbook -i hosts.ini runonce-when.yml

PLAY [run_once combined with when that excludes the first host] ****************

TASK [Only web4 satisfies the condition] ***************************************
skipping: [web1]

TASK [Marker] ******************************************************************
ok: [web1] => {
  "msg": "play continued"
}

PLAY RECAP *********************************************************************
web1                       : ok=1    changed=0    unreachable=0    failed=0    skipped=1

The condition was evaluated on web1, was false, and the task was skipped. It never ran on web4. There is no warning, no error, and the recap shows a clean run with one skipped task — which is what a deliberately skipped task also looks like.

The conditional you meant is not the conditional you wrote

The pattern that produces this is common and looks reasonable:

- name: Seed the cache from the designated node
  ansible.builtin.command: /opt/app/bin/seed-cache
  run_once: true
  when: cache_seed_node | default(false) | bool

The author’s intent is “run this on the node flagged as the seed node”. The behaviour is “check whether the first host is the seed node; if it is not, skip entirely”.

If cache_seed_node: true sits on web4 in host_vars, this task never runs, and the failure surfaces later as an empty cache with no failed task to point at.

Two ways to write what was meant:

# Name the host, do not filter for it
- name: Seed the cache from the designated node
  ansible.builtin.command: /opt/app/bin/seed-cache
  run_once: true
  delegate_to: "{{ groups['cache_seed'] | first }}"

# Or drop run_once and let the condition do the selecting
- name: Seed the cache from the designated node
  ansible.builtin.command: /opt/app/bin/seed-cache
  when: cache_seed_node | default(false) | bool

The second form runs on exactly the hosts where the flag is set — which is what a conditional is for. run_once and when: together are almost always a sign that one of the two is doing a job the other should be doing.

When the `run_once` task fails

The third phrase — “apply any results and facts to all active hosts in the same batch” — includes failure results.

- name: Fails on the one host it runs on
  ansible.builtin.fail:
    msg: "migration failed on {{ inventory_hostname }}"
  run_once: true

- name: Would anyone reach this
  ansible.builtin.debug:
    msg: "reached on {{ inventory_hostname }}"

Read-only / Safeone host fails, nobody continues— Six hosts, no serial. ansible.builtin.fail changes nothing; it exists to produce a failure.

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

TASK [Fails on the one host it runs on] ****************************************
fatal: [web1]: FAILED! => {"changed": false, "msg": "migration failed on web1"}

PLAY RECAP *********************************************************************
web1                       : ok=0    changed=0    unreachable=0    failed=1

The second task did not execute on any host. The recap names only web1, because the other five never produced a result of their own.

This is the behaviour you want. A run_once task is doing shared work — a migration, a schema change, a global switch — and if it failed, no host should proceed as though it succeeded. But note what it means for the recap: the host named in the failure is an implementation detail. It is whichever host the scheduler picked, and it may have nothing to do with where the problem is. Under serial, only that batch stops; later batches run and try the shared work again.

Under the hood

“Apply any results and facts to all active hosts in the same batch” is literal, and it is easy to demonstrate with a fact.

- name: run_once producing a value
  ansible.builtin.set_fact:
    chosen: "picked-by-{{ inventory_hostname }}"
  run_once: true

- name: Who can see it
  ansible.builtin.debug:
    msg: "{{ inventory_hostname }} sees chosen={{ chosen | default('UNSET') }}"

Six hosts, serial: 2, verified on 2.21.3:

TASK [run_once producing a value] **********************************************
ok: [web1]
TASK [Who can see it] **********************************************************
ok: [web1] => { "msg": "web1 sees chosen=picked-by-web1" }
ok: [web2] => { "msg": "web2 sees chosen=picked-by-web1" }

TASK [run_once producing a value] **********************************************
ok: [web3]
TASK [Who can see it] **********************************************************
ok: [web3] => { "msg": "web3 sees chosen=picked-by-web3" }
ok: [web4] => { "msg": "web4 sees chosen=picked-by-web3" }

TASK [run_once producing a value] **********************************************
ok: [web5]
TASK [Who can see it] **********************************************************
ok: [web5] => { "msg": "web5 sees chosen=picked-by-web5" }
ok: [web6] => { "msg": "web6 sees chosen=picked-by-web5" }

The propagation is real — web2 sees a fact it never set — and it is bounded by the batch. web4 sees picked-by-web3, not picked-by-web1. Each batch gets its own value.

That has a consequence for anything that captures a shared result. A run_once task that registers a build identifier, a lock token, a migration version or a timestamp produces a different value per batch, and every host in the play believes it holds the one true value. Templates rendered from it disagree across batches, and the disagreement is invisible in the run output because each host was individually consistent.

If a value must be identical for every host in the play, it cannot come from a run_once task inside that play. It has to come from somewhere that exists once for the whole run: a preceding hosts: localhost play, an extra variable, or a value read from a system of record.

What happens if you combine run_once with delegate_to?

You get the pairing that is almost always correct, and it is worth understanding as two separate decisions rather than one idiom.

- name: Apply pending schema migrations
  ansible.builtin.command: /opt/app/bin/migrate --apply
  args:
    chdir: /opt/app
  run_once: true
  delegate_to: "{{ migration_runner_host }}"

delegate_to answers where: a host you named, the same one on every run, with the tooling and credentials the task needs. run_once answers how often: once per batch, bypassing the host loop.

Adding delegate_to removes the “first host available” problem entirely — the scheduler no longer chooses the machine. It does not fix the per-batch problem: with serial: 5, this still runs once per batch, against the same delegate each time. Three batches means three migration attempts on one host.

So delegate_to fixes one of the two hazards and the other one needs lesson 6.

What to check before trusting a run_once task

Four questions, answerable from the playbook in under a minute:

Does the play have serial, anywhere? Including inherited from an import_playbook or set by a variable. If yes, the task runs once per batch.
Is the task idempotent under repetition? If running it twice is harmless, per-batch execution is a performance annoyance rather than a correctness bug, and you can stop here.
Does it have a when:? If so, the condition is evaluated on one host and decides for the batch. Confirm that is intended.
Does anything downstream use a value it registered or set? If so, that value differs per batch, and every host believes its batch’s value is the value.

Only question 2 lets you stop early, and it is the question worth designing for: a migration that checks its own applied-version table before writing is a migration that survives being run three times.

Knowledge check

Why this matters

run_once is the only keyword in this course whose name is actively misleading, and the gap between what it says and what it does is bridged by a keyword — serial — that gets added months later, by someone else, for reasons that have nothing to do with it.

That combination is what makes it dangerous. The migration task is correct when written. The serial: 5 commit is correct when written. The defect exists only in the interaction, it appears in no diff, and it surfaces as a duplicate-key error on the third batch of a production release.

You cannot review your way out of this by reading tasks in isolation. What you can do is treat run_once as a declaration that a task touches shared state, and hold every one of them to a single standard: either it is safe to run once per batch, or it does not use run_once. The next lesson is about the second option.