serial: batching a play · Ansible

A play with no serial keyword runs on every targeted host at once.

Not “quickly one after another” — at once, in waves of forks, with no gap in which anything could be noticed. If the play restarts a service, every instance of that service goes down together. If the configuration it deploys is wrong, it is wrong everywhere before the first host has finished reporting.

This is the default. It is not a setting anyone chose; it is what a reader gets by not thinking about it, and it is almost never what production wants.

serial is the keyword that changes it.

The default, stated plainly

Service impact possiblea fleet-wide simultaneous restart— No serial keyword. Every host in webservers is reconfigured and restarted in the same pass. On a 200-host group this is a 200-host outage window if the template is wrong.

- name: Deploy the application configuration
hosts: webservers
become: true
tasks:
  - name: Write the application configuration
    ansible.builtin.template:
      src: app.conf.j2
      dest: /etc/app/app.conf
      mode: '0644'
    notify: Restart app

handlers:
  - name: Restart app
    ansible.builtin.systemd_service:
      name: app
      state: restarted

The blast radius of that play is the entire webservers group, and the window in which you could stop it is the length of one task.

Adding one line changes the shape of the whole thing:

Service impact possiblethe same change, staged— One host first, then five, then a quarter of the fleet at a time. Still a service-impacting change, but now there is a point at which a human can look at the result.

- name: Deploy the application configuration
hosts: webservers
become: true
serial:
  - 1
  - 5
  - 25%
tasks:
  - name: Write the application configuration
    ansible.builtin.template:
      src: app.conf.j2
      dest: /etc/app/app.conf
      mode: '0644'
    notify: Restart app

handlers:
  - name: Restart app
    ansible.builtin.systemd_service:
      name: app
      state: restarted

The three forms

serial accepts an integer, a percentage string, or a list of either.

Read-only / Safebatch composition, executed on ansible-core 2.21.3— A six-host inventory of local connections and a single debug task with run_once, printing ansible_play_batch once per batch. No host state is touched.

$ ansible-playbook -i inv6.ini batches.yml

serial: 2
['h01', 'h02']
['h03', 'h04']
['h05', 'h06']

serial: [1, 2, 3]
['h01']
['h02', 'h03']
['h04', 'h05', 'h06']

serial: [2, 4]
['h01', 'h02']
['h03', 'h04', 'h05', 'h06']

serial: 100
['h01', 'h02', 'h03', 'h04', 'h05', 'h06']

An integer larger than the host count produces a single batch. serial never invents hosts and never splits a host.

The list keeps going after it runs out

A list shorter than the fleet needs does not stop at its last entry. The final value repeats until every host has been covered.

Read-only / Safea two-entry list over six and over twenty hosts— Executed on 2.21.3. The last value in the list becomes the steady-state batch size.

$ ansible-playbook -i inv6.ini batches.yml   # serial: [1, 2]

six hosts, serial: [1, 2]
['h01']
['h02', 'h03']
['h04', 'h05']
['h06']

twenty hosts, serial: [1, 2]
['h01']
['h02', 'h03']
['h04', 'h05']
['h06', 'h07']
... continues in twos ...
['h18', 'h19']
['h20']

Upstream states this directly: with serial: [1, 5, 10], “the first batch would contain a single host, the next would contain 5 hosts, and (if there are any hosts left), every following batch would contain either 10 hosts or all the remaining hosts.”

The practical consequence is that a list is a ramp, not a schedule. [1, 5, 25%] does not mean “three batches”. It means “one, then five, then a quarter at a time for as long as it takes”.

A percentage rounds down, and resolves against the whole play

This is the form that surprises people, and it is worth executing rather than assuming.

Read-only / Safepercentage arithmetic, executed on 2.21.3— Six hosts and twenty hosts, several percentages. The batch size is the floor of the percentage applied to the play total, with a floor of one host.

$ ansible-playbook -i inv6.ini batches.yml

six hosts:
serial: "25%"   ->  1, 1, 1, 1, 1, 1     (25% of 6 = 1.5)
serial: "30%"   ->  1, 1, 1, 1, 1, 1     (30% of 6 = 1.8)
serial: "49%"   ->  2, 2, 2              (49% of 6 = 2.94)
serial: "50%"   ->  3, 3                 (50% of 6 = 3.0)
serial: "51%"   ->  3, 3                 (51% of 6 = 3.06)

twenty hosts:
serial: "10%"   ->  2 x 10 batches
serial: "25%"   ->  5, 5, 5, 5
serial: "30%"   ->  6, 6, 6, 2
serial: "33%"   ->  6, 6, 6, 2           (33% of 20 = 6.6)

Three things fall out of that table.

It rounds down, not to nearest. 25% of six hosts is 1.5, and the batch is 1. 33% of twenty is 6.6, and the batch is 6. If you write 33% expecting “roughly a third, three batches”, you get four batches with a ragged tail.

The 30%-of-twenty case matches upstream exactly — the documentation uses this example and gives 6, 6, 6, 2. Executed here, it produces 6, 6, 6, 2.

A percentage always resolves to at least one host. 1% of six hosts is 0.06, and Ansible runs batches of one rather than batches of zero. A play cannot make no progress because someone wrote a small percentage against a small fleet.

The percentage is of the play, not of what is left

In a mixed list, a percentage is applied to the total host count of the play, not to the hosts still remaining.

Verified on 2.21.3 with twenty hosts and serial: [1, 5, "25%"]:

['h01']
['h02', 'h03', 'h04', 'h05', 'h06']
['h07', 'h08', 'h09', 'h10', 'h11']
['h12', 'h13', 'h14', 'h15', 'h16']
['h17', 'h18', 'h19', 'h20']

After the first two batches, fourteen hosts remain — but the third batch is five, not three. 25% means 25% of twenty throughout. Upstream states the rule as “Ansible applies the percentage to the total number of hosts in a play to determine the number of hosts per pass.”

If it resolved against the remainder, the batches would shrink asymptotically and the rollout would never finish.

The play restarts for every batch

This is the mechanism, and almost every surprising serial behaviour follows from it.

A batched play is not one play that pauses. It is the same play executed once per batch, against a different set of hosts each time. The output makes this visible: the PLAY [...] banner repeats.

Read-only / Safesix hosts, serial: 2, executed on 2.21.3— Three PLAY banners for one play in one playbook. Each is a complete execution of every task in the play against two hosts.

$ ansible-playbook -i inv6.ini deploy.yml

PLAY [Handlers per batch] ******************************************************

TASK [Deploy config] ***********************************************************
changed: [h01]
changed: [h02]

RUNNING HANDLER [Restart service] **********************************************
ok: [h01]
ok: [h02]

PLAY [Handlers per batch] ******************************************************

TASK [Deploy config] ***********************************************************
changed: [h03]
changed: [h04]

RUNNING HANDLER [Restart service] **********************************************
ok: [h03]
ok: [h04]

PLAY [Handlers per batch] ******************************************************

TASK [Deploy config] ***********************************************************
changed: [h05]
changed: [h06]

RUNNING HANDLER [Restart service] **********************************************
ok: [h05]
ok: [h06]

Read that as three executions, not as one execution with markers in it. Everything that happens “once per play” now happens once per batch:

Construct	Under `serial: 2` over six hosts
`pre_tasks`	runs three times, once per batch
`post_tasks`	runs three times
Handler flush at end of play	three flushes
`roles:`	applied three times, to different hosts
`run_once: true`	runs three times — once per batch
`gather_facts`	gathers for the batch, not the fleet

The run_once row is the one that causes production incidents, and it gets its own treatment in the delegation part. The short version: run_once means once per batch, so a “run once” database migration under serial: 5 runs as many times as there are batches.

A set_fact from batch one is not visible in batch two

Facts set on a host persist for that host. Facts you reasoned about across the fleet do not survive the batch boundary, because the later batch is a fresh execution whose active host list does not include the earlier hosts.

A pattern that works without serial and silently breaks with it:

- name: Record the current release on every host
  ansible.builtin.set_fact:
    current_release: '{{ installed.stdout }}'

- name: Refuse if the fleet is not on a single release
  ansible.builtin.assert:
    that: ansible_play_hosts | map('extract', hostvars, 'current_release') | unique | length == 1

Without serial, ansible_play_hosts is the fleet and the assertion means something. With serial: 5, it is five hosts, and the assertion checks that five hosts agree with each other — which they will, right up until batch four introduces the host that disagrees.

Fleet-wide preconditions belong in a separate, unbatched play before the rolling one. Put the assertion where it can see the whole fleet.

Knowing which hosts you are in

Three variables answer “who is in scope”, and under serial they stop being the same thing.

Variable	Meaning under `serial`
`ansible_play_batch`	the hosts in this batch that are still active
`ansible_play_hosts`	the same as `ansible_play_batch` in a batched play — active hosts of the current execution
`ansible_play_hosts_all`	every host the play targets, unaffected by batching

Verified on 2.21.3: across all three batches of a serial: 2 run over six hosts, ansible_play_hosts_all | length reported 6 every time, while ansible_play_batch reported the two hosts of that batch.

Read-only / Safeprinting the batch you are actually in— Read-only. A useful first task in any batched play: it puts the batch composition in the run log, which is what you will want during the post-incident reconstruction.

- name: Record which hosts are in this batch
ansible.builtin.debug:
  msg: >-
    batch {{ ansible_play_batch | length }} of
    {{ ansible_play_hosts_all | length }} total:
    {{ ansible_play_batch | join(', ') }}
run_once: true

run_once is exactly right here, because you want one line per batch, and “once per batch” is what run_once actually does.

Choosing a batch shape

The shape encodes what you are afraid of.

serial: 1 — one host at a time. The slowest and the safest. For a fleet of 300 with a two-minute play, that is ten hours, so it is a shape for small critical groups, not for fleets.

serial: [1, 5, 25%] — the canary ramp, and the default answer for most production changes. One host proves the change works at all. Five prove it works on more than a lucky host. Then a quarter at a time, because by that point the risk is different in kind: you are no longer asking “does this work” but “does this scale”.

A percentage alone — serial: "10%" — keeps a fixed proportion of the fleet in flight regardless of how the fleet grows. Reasonable for convergence runs that do not restart anything. As a shape for a service-impacting change it is worse than the ramp, because it puts 10% of the fleet into the first batch, and the first batch is where an untested change is most likely to be wrong.

Capacity is the constraint that overrides all of this. If the service needs 80% of its instances to carry peak traffic, no batch may exceed 20% of the fleet, and that arithmetic has nothing to do with Ansible. Work out the largest batch the service can lose, then choose a serial at or below it.

Under the hood

The batching happens in the play iterator, before any task runs. The linear strategy asks the play for its list of serial batch sizes, then splits the play’s host list into consecutive slices of those sizes.

The relevant behaviour, all confirmed by execution on 2.21.3:

Slicing is positional, in inventory order. Batch one is the first n hosts of the play, not a random sample. This is why the order: keyword matters — order: shuffle reorders the play host list before slicing, which destroys the property that “the canary is the same host every time”. If your canary is meant to be a specific, well-understood host, it must be first in the resolved order, and nothing may shuffle it.

Percentages are resolved once, against the play total. The percentage is converted to an integer batch size using the full host count at play start, then that integer is used for every batch it applies to. This is why [1, 5, "25%"] over twenty hosts gives 5-host batches rather than shrinking ones, and why removing a host from inventory changes every batch size in the run.

Each batch is a full pass through the play’s task list. The strategy runs the complete block-and-task tree for the batch, including the implicit handler flush at the end, then returns to the iterator for the next slice. Nothing in the play object is reset between batches — the task list is the same object — but the host list the tasks execute against is replaced. That is the entire mechanism behind “the play restarts”, and it explains both the repeated PLAY banner and the per-batch handler flush.

What happens if a host is added to inventory mid-rollout?

Nothing, for the run in progress.

The play’s host list is resolved once, at the start of the play, and the batch sizes are computed from it. A host added to a dynamic inventory source while the play is running is not picked up, is not batched, and is not touched. The run finishes against the fleet as it was.

This is usually what you want and occasionally a trap: a fleet that autoscales during a rolling deploy ends with new instances running the old build, because they were created after the play enumerated its hosts. The new instances are not in the recap, so nothing in the run output hints at it.

If you operate an autoscaling group, the image or the bootstrap has to be the thing that carries the new version — a rolling play cannot chase a moving fleet, and believing it can is how you end up with a version split that nobody can explain.

Knowledge check

Why this matters

Every other safety mechanism in this course narrows which hosts a run can touch. serial is the only one that changes when it touches them, and that is a different kind of protection.

A --limit that is wrong is wrong before you press return, and the effective host list will tell you so. A change that is wrong in a way no inventory check could reveal — a template that renders valid configuration the service refuses to load, a package version that conflicts with something only production has — is only discoverable by applying it to a real host and looking at the result.

serial is what buys you the looking. Without it, the interval between “the change is untested” and “the change is on every host” is one task. With serial: [1, 5, 25%], one host carries the risk first, and the run has a point at which stopping is still cheap.

The keyword is one line. The absence of the keyword is a decision too, and it is the one that ships by default.