Ansible run_once: Execute Tasks Once Across All Hosts (Complete Guide)
By Luca Berton · Published 2024-01-01 · Category: database-automation
How to use Ansible run_once to execute a task on a single host. Combine with delegate_to, serial, and throttle for controlled execution. Complete guide with examples.
Ansible run_once: Execute Tasks Once Across All Hosts (Complete Guide)
The run_once directive tells Ansible to execute a task only once for the entire play, regardless of how many hosts are targeted. The task runs on the first host in the batch, and the result is applied to all hosts.
Basic Usage
run_once with delegate_to
A common pattern: run a task once on a specific host, regardless of the play's target hosts.
run_once with register
When run_once is combined with register, the variable is available on all hosts:
run_once with set_fact
run_once vs serial vs throttle
serial — Rolling Updates
throttle — Limit Concurrent Tasks
Comparison
| Directive | What It Does | Use Case | |-----------|-------------|----------| | run_once: true | Run on first host only | DB migrations, cache purges, one-time setup | | serial: N | Process N hosts per batch | Rolling deployments, zero-downtime updates | | throttle: N | Max N concurrent executions | Rate-limited APIs, bandwidth constraints | | delegate_to: host | Run on specific host | Cross-host operations |
Common Patterns
Zero-Downtime Deployment
Pre/Post Deployment Tasks
FAQ
What does run_once do in Ansible?
run_once: true executes a task only once for the entire play, on the first host in the batch. The result (including registered variables) is shared with all other hosts. Use it for tasks that should happen once per deployment, like database migrations.
Does run_once set registered variables on all hosts?
Yes. When you combine run_once: true with register, the registered variable is available on all hosts in the play, not just the host where the task ran.
What is the difference between run_once and delegate_to?
run_once controls how many times a task runs (once). delegate_to controls where a task runs (specific host). They're often combined: run_once: true + delegate_to: db01 means "run this once, on db01."
Can I use run_once with serial?
Yes, but be careful. With serial, run_once executes once per batch, not once for the entire play. If you have 10 hosts with serial: 5, the task runs twice (once per batch of 5).
When should I use run_once vs running a separate play?
Use run_once when the task is part of the same workflow (e.g., migrate DB before deploying app). Use a separate play when the task targets different hosts or needs different become/connection settings.
Conclusion
run_once is essential for deployment workflows where certain tasks (migrations, cache purges, notifications) should only happen once. Combine with delegate_to for cross-host operations and serial for rolling updates.
Related Articles • Ansible delegate_to: Run Tasks on Different Hosts • Ansible Handlers: Run Tasks on Change • Ansible Playbook: Complete Guide
Category: database-automation