Performance Tuning

Because Ansible has no agent doing local work, almost all of its runtime is SSH and process overhead — every task is potentially a new connection, a module copy, and a Python invocation on the target. Tuning Ansible is therefore tuning that overhead, not optimizing some local engine, because there is no local engine on the host to optimize.

The single biggest win is pipelining, which collapses the multiple SSH operations per task into one. Stack pipelining, connection multiplexing, more forks, and skipping unneeded fact gathering, and a deploy across Larkspur's 6 prod web hosts goes from minutes to a fraction of that. These settings are complementary — you turn them all on, not pick one — and the sections below take them in order of impact.

Pipelining — the Biggest Single Win

pipelining = True, set under [ssh_connection], feeds the module to the remote Python over the existing SSH session instead of copying a temp file and executing it as a separate step. That cuts the SSH operations per task roughly in half — one round-trip where there were two or three. The one requirement is that the target's sudoers has no requiretty, because pipelining runs the module without an allocated TTY; if sudoers still demands a TTY, escalated tasks fail. Clear that requirement once and pipelining costs nothing thereafter.

ControlPersist and SSH Multiplexing

The ssh connection's ControlPersist keeps one SSH master socket open and routes every subsequent task through it, so a 40-task play pays one handshake instead of forty. This is on by default with the ssh plugin — you inherit it for free — and the only thing you usually tune is the persist timeout, with ssh_args = -o ControlPersist=60s for long runs where the master would otherwise time out between phases. Pipelining and multiplexing stack: one reuses the connection, the other reduces operations per task on top of it.

forks — Host Parallelism

forks sets how many hosts Ansible acts on at once, and it defaults to 5. With Larkspur's 6 prod web hosts and the default, the sixth host waits for a slot — the deploy runs in two serial waves, five hosts then one, for no reason but a low default. Raising forks to 20 lets the whole web tier run in a single parallel wave, and the deploy finishes in one pass. The rule of thumb is to set forks at least to the size of your largest tier.

[defaults]
forks = 20                  # the whole 6-host web tier runs in one wave
gathering = smart
fact_caching = jsonfile
fact_caching_connection = .ansible_facts

[ssh_connection]
pipelining = true           # biggest single win — needs requiretty off in sudoers
ssh_args = -o ControlPersist=60s

Every line here trims overhead Ansible would otherwise pay on each run: pipelining halves SSH operations per task, ControlPersist holds the master open across tasks, forks = 20 parallelizes the tier, and fact caching avoids re-gathering. None of them change what the playbook does — they change how much wire and process cost the same playbook pays.

Skipping Fact Gathering

gather_facts: false on a play that reads no facts skips an entire setup round-trip per host — the implicit fact-gathering task is one of the most expensive things a play does, and paying for it when nothing references a fact is pure waste. When you need only some facts, gather_subset: ['!all', 'min'] (or naming specific subsets) gathers the minimum instead of everything. The cheapest fact gathering is the one you don't run, and the second cheapest is the one scoped to exactly what the play reads.

Fact Caching

fact_caching — backed by jsonfile or redis — stores gathered facts between runs so repeated plays reuse them instead of re-gathering. That turns a per-run cost into a periodic one: the facts are collected when the cache is cold or stale, and every run in between reads them from the cache. It is worth enabling when the same fleet is targeted often, exactly as Larkspur's CI does on every push, where re-gathering the same six hosts' facts on every pipeline run is cost you can amortize away.

strategy: free

By default the linear strategy makes every host finish a task before any host starts the next, so the slowest host paces the whole play. strategy: free lets each host race ahead through its own task list, finishing fast hosts early instead of holding them at a barrier. It is good for independent per-host work, but the tradeoff is real: ordering across hosts is no longer lockstep, so anything that depends on hosts moving together — a coordinated rolling sequence — must stay on linear.