linear, free and host_pinned · Ansible

The default strategy has a property nobody notices until it is gone: when task 3 finishes, every host has finished task 3. That is a barrier, and a great deal of what this course teaches about staged, verifiable change rests on it.

strategy: free removes it. That is faster, and it is not a free improvement — it is a trade, and the thing being traded away is the reason a rolling deployment is meaningful rather than just parallel.

Four, and only four

Read-only / Safethe complete list in ansible.builtin— ansible-core 2.21.3 with no collections installed. This is every strategy plugin core ships.

$ ansible-doc -t strategy -l

ansible.builtin.debug       Executes tasks in interactive debug session
ansible.builtin.free        Executes tasks without waiting for all hosts
ansible.builtin.host_pinned Executes tasks on each host without interruptio...
ansible.builtin.linear      Executes tasks in a linear fashion

Three of them are execution strategies and one is a debugger. strategy is a Play keyword only — it cannot be set per task or per block — and the default is linear, which ansible-config dump confirms as DEFAULT_STRATEGY(default) = linear.

`linear`: the barrier you are used to

One task at a time, across all hosts in the current batch, and the play does not advance until every host has finished that task or dropped out. forks decides how many of those hosts are worked on simultaneously; the barrier is unaffected by it.

Read-only / Safelinear: nobody moves on until everybody has— Three hosts. web1 waits six seconds on task A; web2 and web3 wait zero. Verified on ansible-core 2.21.3 with local connections and wait_for, which sleeps and touches nothing.

$ ansible-playbook -i strat.ini strat.yml -f 5

TASK [Task A (web1 is slow)] ***************************************************
ok: [web2]
ok: [web3]
ok: [web1]

TASK [Task B] ******************************************************************
ok: [web1] => { "msg": "B on web1" }
ok: [web2] => { "msg": "B on web2" }
ok: [web3] => { "msg": "B on web3" }

TASK [Task C] ******************************************************************
ok: [web1] => { "msg": "C on web1" }
ok: [web2] => { "msg": "C on web2" }
ok: [web3] => { "msg": "C on web3" }

web2 and web3 finished task A immediately and then waited six seconds for web1 before anyone started task B. That waiting is the cost, and it is exactly what free recovers.

Note also that the ok: lines under task A are in completion order — web2, web3, then web1. linear dispatches in parallel up to forks and prints results as they arrive; it is the advance to the next task that is synchronised, not the dispatch.

`free`: no barrier

Read-only / Safefree: each host runs ahead on its own— Identical playbook and inventory, strategy free. Verified on 2.21.3.

$ ansible-playbook -i strat.ini strat.yml -f 5 -e strat=free

TASK [Task A (web1 is slow)] ***************************************************
ok: [web2]
ok: [web3]

TASK [Task B] ******************************************************************
ok: [web2] => { "msg": "B on web2" }
ok: [web3] => { "msg": "B on web3" }

TASK [Task C] ******************************************************************
ok: [web2] => { "msg": "C on web2" }
ok: [web3] => { "msg": "C on web3" }

TASK [Task A (web1 is slow)] ***************************************************
ok: [web1]

TASK [Task B] ******************************************************************
ok: [web1] => { "msg": "B on web1" }

TASK [Task C] ******************************************************************
ok: [web1] => { "msg": "C on web1" }

web2 and web3 completed the entire play — A, B and C — before web1 finished task A. The task banner is reprinted when a host reaches a task the output has moved past.

The upstream description matches what was observed: “Ansible will not wait for other hosts to finish the current task before queuing more tasks for other hosts… a host that is slow or stuck on a specific task will not hold up the rest of the hosts and tasks.”

That output block is also the honest picture of what a free run looks like to read. Task banners repeat, hosts appear out of order, and there is no moment at which the transcript tells you the fleet is in a consistent state.

free is incompatible with a staged change

A rolling deployment is a sequence of steps where each step depends on the previous one having completed across the batch:

- name: Drain from the pool
  ...
- name: Wait for connections to finish
  ...
- name: Deploy the new version
  ...
- name: Health check
  ...
- name: Return to the pool
  ...

Under linear, when the health check task completes, every host in the batch has been drained, deployed and checked. That is what makes the next step safe and what makes an abort at step 3 leave the fleet in a state you can describe.

Under free, host 1 can be back in the pool serving traffic on the new version while host 12 has not yet been drained. If something is wrong with the release, you find out from host 1 while eleven others are already mid-change, and there is no task boundary at which to stop cleanly. The sequence still exists per host; the coordination does not.

serial still batches under free — the plugin documentation says execution is as fast as possible “per batch as defined by serial” — so you keep the batch boundaries and lose the task boundaries inside them. That is usually the worst of both: a rollout that still takes as long as its batches but can no longer tell you where it is.

Do not set strategy: free on a play that performs a staged change. If a run is slow because of one straggler in a rolling deployment, the straggler is the problem, not the barrier.

`host_pinned`

The description is precise about what it does and it is worth reading carefully, because the name suggests something narrower:

“Task execution is as fast as possible per host in batch as defined by serial (default all). Ansible will not start a play for a host unless the play can be finished without interruption by tasks for another host, i.e. the number of hosts with an active play does not exceed the number of forks. Ansible will not wait for other hosts to finish the current task before queuing the next task for a host that has finished. Once a host is done with the play, it opens its slot to a new host that was waiting to start. Other than that, it behaves just like the free strategy.”

So: free, with an additional rule that a host is only started when a worker slot is available for it to run to completion, and slots are recycled as hosts finish.

Where that earns its place is a play that holds a scarce resource for its whole duration — a licence checkout, a maintenance-window slot, a database connection from a small pool. Under free, forks hosts start and all of them hold the resource concurrently for as long as any of them is slow. Under host_pinned, the number of hosts with a play in progress stays bounded and each one finishes before another begins.

It is still barrier-free. Everything the callout above says about staged changes applies to host_pinned unchanged.

`debug`

Not a performance strategy. It drops into an interactive debugger when a task fails, letting you inspect and re-run it. It forces serialised execution as a side effect of being interactive, which makes it useless for anything except debugging — and the debugging technique itself belongs to this course’s troubleshooting part.

Do not leave strategy: debug in a committed playbook. A run that stops for an interactive prompt in an unattended context is a run that hangs until someone notices.

Choosing

Situation	Strategy
Any staged change: drain, deploy, verify, restore	`linear`. Not negotiable
Anything with handlers whose timing matters	`linear`
A long play over many hosts where hosts are independent of each other	`free` is worth measuring
As above, but the play holds a scarce resource per host	`host_pinned`
Diagnosing a failing task interactively	`debug`, never committed

The default is linear and the default is right for most plays. free is a specific optimisation for a specific shape: independent hosts, a long task list, and a known straggler problem.

Before switching, check whether the straggler is the real finding. A host that takes six seconds where others take zero is telling you something — disk pressure, a slow package manager, a network path — and free hides that message by routing around it.

Under the hood

The barrier is not only about ordering. Several behaviours are defined in terms of “the current task across the batch”, and removing the barrier changes what they can mean.

Handlers. Handlers are flushed at the end of a play or batch, not at arbitrary points. Under free, hosts reach that flush at different times, so a notified restart happens per host whenever that host gets there. For a handler that restarts a service, that is usually fine. For a handler whose whole purpose is to restart something after the fleet agrees on a configuration, it is not.

run_once. The keyword bypasses the host loop and applies results to active hosts in the batch. Under free, hosts arrive at the task at wildly different times, and reasoning about which host got there first is guesswork rather than the tidy first-of-the-batch answer from the delegation part.

Reading the output. Under linear, the last task banner tells you what the whole batch is doing. Under free it tells you what some host is doing, and the banner can be reprinted many times. For a run somebody is watching during a change window, that is a real loss — the transcript stops being a status display.

max_fail_percentage. It is evaluated at batch boundaries. Under free those boundaries still exist, but hosts within a batch can be arbitrarily far apart in the task list when a failure occurs, so the set of hosts that have already applied the change when the play aborts is much less predictable.

None of these is a bug. They are all consequences of the same removal, and they are the reason the choice belongs to the play rather than to a global default.

What happens if you set strategy: free globally in ansible.cfg?

Every play in every playbook loses the barrier, including the ones written by people who assumed it.

DEFAULT_STRATEGY is a configuration setting, so this is one line:

[defaults]
strategy = free

It will make some runs faster and it will silently change the semantics of every rolling deployment in the repository. A play that reads correctly — drain, deploy, verify, restore — no longer does what it says, and nothing in that playbook mentions strategy, so nobody reviewing it has a reason to think about the change.

If a specific play benefits from free, set it on that play, where it is visible next to the tasks it affects:

- name: Collect inventory data from every host
  hosts: all
  strategy: free
  gather_facts: false
  tasks:
    - name: Read the installed package set
      ...

That example is the right shape for free: a read-only survey where hosts have nothing to do with each other and there is no state to keep consistent. Even then, measure it — if the play is dominated by fact gathering or by one slow task on every host, free changes nothing, because there is no straggler to route around.

Knowledge check

Why this matters

free is presented in most tuning advice as a switch that makes Ansible faster, and the framing is wrong in a way that matters. It does not make the work faster; it stops hosts waiting for each other. What you get back is the time your fastest hosts spent idle, and what you give up is the guarantee that lets you say where the fleet is.

For a read-only survey across independent hosts, that trade is obviously worth making. For a rolling deployment it is the specific guarantee the deployment is built on, and removing it turns a staged change into a parallel one with the same YAML.

There is also a quieter argument against reaching for it. A run that is slow because of one straggler has told you something true about that machine. free routes around the message. Before you optimise away the waiting, find out what the fleet was waiting for.

Four, and only four

linear: the barrier you are used to

free: no barrier

host_pinned

debug

Knowledge check

`linear`: the barrier you are used to

`free`: no barrier

`host_pinned`

`debug`