Ansible playbook --limit: Run on Specific Hosts (Complete Guide)
By Luca Berton · Published 2024-01-01 · Category: troubleshooting
How to use Ansible playbook --limit to target specific hosts, groups, and patterns. Limit execution to one host, exclude hosts, use regex patterns.
Ansible playbook --limit: Run on Specific Hosts (Complete Guide)
The --limit flag (or -l) restricts playbook execution to specific hosts or groups from your inventory. It's essential for targeted deployments, testing on single hosts, and rolling updates.
See also: Three options to Safely Limit Ansible Playbooks Execution to a Single Machine
Basic Usage
# Run on a single host
ansible-playbook site.yml --limit web01
# Run on multiple hosts
ansible-playbook site.yml --limit "web01,web02"
# Run on a group
ansible-playbook site.yml --limit webservers
# Run on multiple groups
ansible-playbook site.yml --limit "webservers,dbservers"Host Patterns
Single Host
ansible-playbook deploy.yml --limit web01.example.com
ansible-playbook deploy.yml -l web01Multiple Hosts (Comma-Separated)
ansible-playbook deploy.yml --limit "web01,web02,web03"Entire Group
ansible-playbook deploy.yml --limit production
ansible-playbook deploy.yml --limit webserversMultiple Groups (Union)
# Hosts in webservers OR dbservers
ansible-playbook deploy.yml --limit "webservers,dbservers"Group Intersection (AND)
# Hosts in BOTH webservers AND production
ansible-playbook deploy.yml --limit "webservers:&production"Exclude Hosts/Groups (NOT)
# All webservers EXCEPT web03
ansible-playbook deploy.yml --limit "webservers:!web03"
# All production EXCEPT dbservers
ansible-playbook deploy.yml --limit "production:!dbservers"Wildcard Patterns
# All hosts starting with web
ansible-playbook deploy.yml --limit "web*"
# All .example.com hosts
ansible-playbook deploy.yml --limit "*.example.com"Regex Patterns
# Regex (prefix with ~)
ansible-playbook deploy.yml --limit "~web[0-9]+"
ansible-playbook deploy.yml --limit "~(web|app).*\.prod\.example\.com"Numeric Range
# web01 through web05
ansible-playbook deploy.yml --limit "web[01:05]"See also: Ansible Playbook --limit: Target Specific Hosts & Groups (Guide)
Combining Patterns
# webservers in production, excluding web03
ansible-playbook deploy.yml --limit "webservers:&production:!web03"
# All servers except staging group
ansible-playbook deploy.yml --limit "all:!staging"
# First host in webservers group only
ansible-playbook deploy.yml --limit "webservers[0]"Using --limit with retry files
When a playbook fails on some hosts, Ansible creates a .retry file:
# Re-run only on failed hosts
ansible-playbook site.yml --limit @site.retrySee also: AAP 2.6 ansible-navigator: Modern CLI for Automation Development
Limit in Playbook (hosts directive)
You can also limit at the playbook level:
---
# Option 1: Use a variable (combine with --limit or -e)
- hosts: "{{ target_hosts | default('all') }}"
tasks:
- ansible.builtin.debug:
msg: "Running on {{ inventory_hostname }}"ansible-playbook deploy.yml -e "target_hosts=web01"Practical Examples
Rolling Deployment (One Host at a Time)
# Deploy to web01 first, verify, then the rest
ansible-playbook deploy.yml --limit web01
# ... verify ...
ansible-playbook deploy.yml --limit "webservers:!web01"Test on Staging Before Production
ansible-playbook deploy.yml --limit staging
# ... verify ...
ansible-playbook deploy.yml --limit productionEmergency Fix on Single Server
ansible-playbook fix-nginx.yml --limit web03.example.comCanary Deployment
# Deploy to 1 host first
ansible-playbook deploy.yml --limit "webservers[0]"
# Then the rest
ansible-playbook deploy.yml --limit "webservers[1:]"--limit with Ad-Hoc Commands
# Ping specific hosts
ansible all --limit "web01,web02" -m ping
# Check uptime on production webservers
ansible webservers --limit "&production" -m shell -a "uptime"Common Mistakes
1. Forgetting quotes with special characters
# WRONG — shell interprets ! and &
ansible-playbook site.yml --limit webservers:!web03
# CORRECT — quote the pattern
ansible-playbook site.yml --limit "webservers:!web03"2. Limit doesn't override hosts directive
# If playbook says hosts: webservers
- hosts: webservers
tasks: ...# --limit "dbservers" won't match anything because
# the play only targets webservers
ansible-playbook site.yml --limit dbservers
# Result: no hosts matched3. Case sensitivity
Host names and group names are case-sensitive in the inventory:
# Won't match if inventory has "WebServers"
ansible-playbook site.yml --limit webserversFAQ
How do I run an Ansible playbook on one specific host?
Use --limit hostname: ansible-playbook playbook.yml --limit web01. The host must be in your inventory and match the play's hosts directive.
How do I exclude a host from an Ansible playbook run?
Use the ! (NOT) pattern: --limit "all:!web03" or --limit "webservers:!web03". Quote the pattern to prevent shell interpretation of !.
Can I use --limit with ansible-playbook and ad-hoc commands?
Yes. Both ansible-playbook and ansible ad-hoc commands accept --limit (or -l). The pattern syntax is identical.
What happens if --limit matches no hosts?
Ansible will show "no hosts matched" and skip the play. No tasks will execute. Use --list-hosts to preview which hosts would be targeted: ansible-playbook site.yml --limit "pattern" --list-hosts.
How do I retry only failed hosts?
After a failure, Ansible creates a playbook.retry file listing failed hosts. Run ansible-playbook playbook.yml --limit @playbook.retry to retry only those hosts.
Conclusion
The --limit flag is essential for targeted Ansible execution. Use it for single-host testing, rolling deployments, canary releases, and emergency fixes. Combine with patterns (:& for intersection, :! for exclusion) for precise host targeting.
Related Articles
Category: troubleshooting