forks, serial, and Rolling Updates

Two numbers govern how a play touches a fleet, and they are constantly mixed up. forks is control-node parallelism — how many hosts Ansible talks to simultaneously, default 5. serial is batch size — how many hosts a play runs against per wave before moving to the next batch, the mechanism a rolling deploy is built on. Raising forks makes the run faster; setting serial makes the run safer.

The two answer different questions, and the rest of this topic keeps them apart deliberately before assembling them into the rolling deploy this chapter is heading toward. Get the distinction wrong and you either run a slow deploy that you think is safe, or a fast one that quietly lands everywhere at once.

forks — Control-Node Concurrency

forks caps how many parallel connections the control node opens at once. The default is 5, set in ansible.cfg or overridden with --forks. With Larkspur's six prod web hosts and forks: 5, the control node works five hosts in parallel and the sixth waits for a slot to free up — but every host still runs the same play to completion. forks changes nothing about which hosts run or in what grouping; it only changes how many connections are live at any instant.

This is purely a speed knob. Raise it and a wide play finishes sooner because more hosts are worked in parallel; leave it too low on a large fleet and the run is connection-starved, crawling through hosts a handful at a time while you wrongly conclude Ansible is slow.

serial — Batch Size Per Wave

serial is a different idea entirely. serial: 2 runs the entire play against two hosts, finishes them completely, then runs the entire play against the next two, and so on. This is what turns "deploy to all six at once" into "deploy two at a time," so a bad release fails on a small wave instead of landing everywhere simultaneously. Where forks is about connections, serial is about waves — it slices the host list into batches and runs the whole play per batch.

That batching is the foundation of every rolling deploy. The fleet is never touched all at once; it is rolled through in controlled chunks, and the size of each chunk is the blast radius you have chosen to accept.

serial as a Ramping List

serial also accepts a list, which is how you build a canary. serial: [1, 2, 3] makes the first batch a single host, the next batch two hosts, the next three. You prove the change on one host, widen to two once it holds, then accelerate. If the canary breaks, the play has touched exactly one host, not the fleet. The list shape lets a rollout start cautious and speed up only after the risk has been retired.

- hosts: web
  serial:
    - 1               # wave 1: the canary — one host
    - 2               # wave 2: two more, once the canary holds
    - 3               # wave 3: the remaining three
  become: true
  tasks:
    - name: Deploy the new larkspur release
      ansible.builtin.git:
        repo: https://github.com/larkspur-io/app.git
        dest: /opt/larkspur
        version: "{{ release_tag }}"

serial with Percentages

serial also takes a percentage. serial: "25%" sizes each batch as a fraction of the targeted hosts, so the same play scales its batch size whether the prod web tier is six hosts or sixty without anyone editing a number. The percentage is computed against the targeted host count and rounds up, which matters on odd-sized tiers — "50%" of six is three, but on a tier of seven it is four, not three-and-a-half. When the exact wave size matters, confirm it with a dry run rather than mental math.

Putting Them Together for a Rolling Deploy

The two knobs combine cleanly once you see what each owns. serial defines the rollout waves — how many hosts are in play at a time. forks defines how fast each wave executes internally — how many of that wave's connections run in parallel. A rolling web deploy is serial: 1 over the web group, with forks set high enough that the rest of the play — fact gathering, package steps on whatever hosts are in the wave — is not artificially throttled.

At serial: 1 there is only ever one host in a wave, so forks barely matters for that play; its value shows when waves contain many hosts. Keep the two settings conceptually separate: forks is the speed setting, serial is the safety setting, and the next topic adds the delegation that lets each one-host wave drain itself from the load balancer first.