Ansible playbook --limit: Run on Specific Hosts (Complete Guide)

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 web01

Multiple Hosts (Comma-Separated)

ansible-playbook deploy.yml --limit "web01,web02,web03"

Entire Group

ansible-playbook deploy.yml --limit production
ansible-playbook deploy.yml --limit webservers

Multiple 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.retry

See 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 production

Emergency Fix on Single Server

ansible-playbook fix-nginx.yml --limit web03.example.com

Canary 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 matched

3. 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 webservers

FAQ

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

• Ansible Inventory: Complete Guide • Ansible Playbook: Complete Guide • Run Ansible Playbook on One Host