Cross-host batching
An opt-in setting that lets each host run ahead through tasks that do not depend on the others.
Batching lets each host run ahead through the tasks that do not depend on other hosts, so a play over many hosts finishes sooner. It is opt-in: it is off unless you turn it on.
By default Volant runs a play the way Ansible’s linear strategy does: the hosts of a batch meet in front of every task. That guarantee lets a playbook depend on things its tasks never mention. One host can write a file another host reads later, or restart a service another host connects to. None of that shows in the text of a task, so the only safe assumption is that any task may depend on the one before it, on every host.
This page covers the default linear strategy. Under strategy: free and host_pinned each host runs at its own pace, run_once, any_errors_fatal and max_fail_percentage are ignored with a warning, and a pause or add_host task stops the run. The hosts meet only at the meta tasks that act on the whole batch (end_play, end_batch, clear_facts, clear_host_errors and refresh_inventory), at handlers and at dynamic includes, whatever batching says. See Other strategies.
What batching changes
Section titled “What batching changes”With batching on, a host carries on through its tasks instead of waiting at each one, and only stops at a synchronization point:
- a
run_onceorpausetask - a task whose text names another host’s state through
hostvars,ansible_play_hostsoransible_play_batch - a task that reads such a name indirectly: through the body of a template whose
srcis fixed, or through a variable whose definition reads another host, however many variables the chain goes through - a delegated task, since the host it acts on may not have got there yet
- a task that reads a controller file after a task that may have written one, such as a
fetch - a point where an include or a handler flush adds steps to the play
- the end of the play
A synchronization point holds on both sides: no host runs past it until every host has finished the step before it.
While a fact that the playbook wrote during the run is still a template, every step is a synchronization point again.
A few more things end a batch without making every host wait: a task that registers a result, a module that can return facts (set_fact, setup, package_facts, any module from a collection or a role’s library/), and a task that calls a lookup. The tasks after them are rendered only once they have run.
linear (default)every host meets in front of every task
batching = truea host only waits at a synchronization point
It changes the order tasks run in, not what they do. The recap is the same either way. What can differ is a dependency the text does not show: with batching on, one host may reach task five before another host has run task one.
What it cannot see
Section titled “What it cannot see”Batching decides from the playbook’s text. A dependency that the text never spells out has no mark, and nothing waits for it:
- a network service another host is still installing:
wait_for: host=db1 port=5432, auricall,psql -h db1, any client that names a host literally; - a file on a host named literally, a shared filesystem, or a database or queue where two hosts’ tasks meet;
- anything a
shellorcommandtask does to another machine.
A computed read such as vars[name] or lookup('vars', name) keeps the synchronization point, since the text cannot say which host it reads. Under ansible-core, and under Volant’s default, every task is a synchronization point, so these orderings hold without anyone writing them down. Turn batching on only for plays whose hosts do not depend on each other in these ways.
Turning it on
Section titled “Turning it on”It is off unless you ask for it.
[volant]batching = trueVOLANT_BATCHING=1 volant playbook -i inventory.ini site.ymlAnsible ignores sections it does not know. Measured on ansible-core 2.19.12 with the block above: ansible-playbook runs the play and exits 0 without a warning, and ansible-config dump does not list the section. One ansible.cfg can carry [volant] and still drive both engines.
What it saves
Section titled “What it saves”Measured with Volant 0.1.0-alpha.5 on one Linux machine, with 200 hosts, 20 tasks, local connections and -f 50: a play in which no task reads another host takes 1.28 s by default and 0.53 s with batching = true, 2.4 times as fast. When every task reads hostvars, both settings take about 1.3 s, since every task is a synchronization point either way. Over SSH each task also pays a network round trip, so your own ratio depends on your latency. These figures have not been measured again since alpha.5.
Why it is not a playbook keyword
Section titled “Why it is not a playbook keyword”Ansible has no such keyword, and a playbook run with Volant must stay a playbook that ansible-playbook runs the same way. Batching describes the machine you run from, so the setting lives in ansible.cfg. Decision record 0005 records the rule behind it.