Ansible delegate_to: Run Tasks on Different Hosts (Complete Guide)
By Luca Berton · Published 2024-01-01 · Category: database-automation
Complete guide to Ansible delegate_to. Run tasks on localhost, delegate to load balancers, execute on different hosts, use with serial, and understand delegation vs connection with practical examples.
The delegate_to directive runs a task on a different host than the current play target, while keeping the context (variables, facts) of the original host. It's essential for load balancer management, local file operations, cross-host coordination, and API calls from the controller.
Basic Syntax
The task runs on localhost but inventory_hostname and other variables still refer to the original target host.
Common Use Cases
Run on Localhost (Controller)
Remove from Load Balancer Before Maintenance
Delegate to Another Host in the Inventory
Cross-Host Database Operations
local_action (Shorthand)
local_action is a shorthand for delegate_to: localhost:
> Recommendation: Use delegate_to: localhost — it's more explicit and consistent.
delegate_to with run_once
Combine for tasks that should run exactly once on a specific host:
delegate_facts
By default, facts gathered during a delegated task are assigned to the original host. Use delegate_facts: true to assign them to the delegated host:
Connection Behavior
When you delegate a task, Ansible connects to the delegated host using that host's connection settings:
Override Connection for Delegation
Delegation in Handlers
Real-World Patterns
Rolling Update with LB Drain
Collect Info from All Hosts Locally
Common Mistakes
Forgetting Variable Context
Missing run_once with delegate_to
FAQ
What does delegate_to do in Ansible?
delegate_to runs a task on a different host than the play target while keeping the original host's variables and facts. For example, you can manage a load balancer from a web server play, or save files locally while iterating over remote hosts.
What is the difference between delegate_to localhost and local_action?
They're functionally equivalent. delegate_to: localhost is more explicit and is the recommended syntax. local_action is an older shorthand that's less commonly used in modern playbooks.
Do variables change when using delegate_to?
No, variables like inventory_hostname, ansible_host, and gathered facts still reference the original play target, not the delegated host. Use hostvars['delegated_host'] to access the delegated host's variables.
Can I delegate to a host not in my inventory?
Yes, but you need to ensure Ansible can connect to it. You may need to add connection parameters inline or define the host in your inventory with appropriate connection settings.
What is delegate_facts?
When delegate_facts: true is set, facts gathered during a delegated task are stored under the delegated host (not the original). Without it, facts from a delegated setup task would be assigned to the wrong host.
Conclusion
delegate_to is essential for cross-host coordination: • delegate_to: localhost — API calls, local file ops, notifications • delegate_to: lb_host — Load balancer management during deploys • delegate_to + run_once — One-time actions on a specific host • delegate_facts: true — Assign gathered facts to the right host • Variables stay with original host — Use hostvars for delegate host data
Related Articles • Execute Command on Ansible Host (localhost) • Ansible register: Save Task Output to Variables • Ansible Handlers: Trigger Actions on Change • Ansible Variable Precedence: Complete Guide
Category: database-automation