Ansible Tags: Run Specific Tasks Selectively (Complete Guide)

Ansible tags are a feature that allows users to selectively control which tasks in a playbook are executed. They are an essential tool for optimizing automation workflows, especially in complex playbooks. This article explains what Ansible tags are, their usage, and best practices for implementing them.

What Are Ansible Tags?

Tags in Ansible are labels assigned to tasks or plays within a playbook. They enable users to execute specific parts of a playbook, skipping others based on the tags provided during execution.

Key Features:

• Selective Execution: Run only tasks with specified tags. • Improved Efficiency: Save time by skipping unnecessary tasks. • Flexibility: Apply multiple tags to a single task or play.

See also: Can Ansible Be Used to Manage Windows Systems?

How Do Ansible Tags Work?

Tags are added to tasks, roles, or entire plays using the tags keyword. During playbook execution, you can specify which tags to include or skip using command-line options.

Example: Using Tags in a Playbook

- name: Configure web servers
  hosts: webservers
  tasks:
    - name: Install Nginx
      apt:
        name: nginx
        state: present
      tags:
        - install
        - web
- name: Start Nginx service
      service:
        name: nginx
        state: started
      tags:
        - start
        - web

In this example: • The install tag applies to the Nginx installation task. • The start tag applies to the task starting the Nginx service. • Both tasks share the web tag.

Running Tagged Tasks

To execute only tasks with a specific tag, use the --tags option:

ansible-playbook playbook.yml --tags install

Skipping Tags

To skip tasks with specific tags, use the --skip-tags option:

ansible-playbook playbook.yml --skip-tags start

Tagging Roles and Plays

Tags can also be applied to roles and entire plays for broader control.

Example: Tagging Roles

- hosts: all
  roles:
    - role: webserver
      tags:
        - setup

Example: Tagging Plays

- name: Database setup
  hosts: dbservers
  tags:
    - database

See also: Can Ansible Manage Windows? Complete Windows Automation Guide

Use Cases for Ansible Tags

Selective Testing: Run specific tasks during testing without executing the entire playbook. Environment-Specific Tasks: Use tags to differentiate tasks for production, staging, or development environments. Debugging: Isolate tasks with issues for quicker debugging. Partial Updates: Apply updates to only certain parts of your infrastructure.

Best Practices for Using Tags

Use Descriptive Tags: Name tags based on their purpose (e.g., install, deploy, restart). Organize Tags: Group related tasks under shared tags for better management. Avoid Overuse: Limit the number of tags to maintain clarity and simplicity. Document Tags: Include a list of available tags in your playbook’s documentation or comments. Test Tagged Tasks: Regularly test tasks under each tag to ensure reliability.

See also: Ansible on Windows: Complete Guide to Windows Automation (2026)

Limitations of Tags

• Dependency Issues: Tasks that depend on others may fail if skipped. • Complexity: Overusing tags can complicate playbooks and execution workflows.

Conclusion

Ansible tags provide a powerful way to control playbook execution, enabling selective task runs and improving efficiency. By implementing tags strategically and following best practices, you can streamline your automation workflows and save valuable time.

Learn More About Ansible Tags

Basic Tags

tasks:
  - name: Install packages
    ansible.builtin.package:
      name: nginx
    tags: install
- name: Configure nginx
    ansible.builtin.template:
      src: nginx.conf.j2
      dest: /etc/nginx/nginx.conf
    tags: configure
- name: Start service
    ansible.builtin.service:
      name: nginx
      state: started
    tags: service

Run or Skip Tags

# Run only tagged tasks
ansible-playbook site.yml --tags "install"
ansible-playbook site.yml --tags "install,configure"
# Skip specific tags
ansible-playbook site.yml --skip-tags "configure"
# List all tags in playbook
ansible-playbook site.yml --list-tags

Multiple Tags Per Task

- name: Deploy app config
  ansible.builtin.template:
    src: config.j2
    dest: /etc/myapp/config.yml
  tags:
    - configure
    - deploy
    - myapp

Tag Roles

- hosts: webservers
  roles:
    - { role: common, tags: common }
    - { role: webserver, tags: [web, nginx] }
    - { role: monitoring, tags: monitoring }

Tag Entire Plays

- hosts: webservers
  tags: webservers
  tasks:
    - name: All tasks inherit the play tag
      package:
        name: nginx

Special Tags

| Tag | Description | |-----|-------------| | always | Always runs (unless --skip-tags always) | | never | Never runs (unless --tags never or explicit) | | tagged | All tagged tasks | | untagged | All untagged tasks | | all | Everything (default) |

- name: Debug info (only when asked)
  debug:
    msg: "Debug mode active"
  tags: never  # Must explicitly --tags debug,never
- name: Gather facts (always)
  setup:
  tags: always

Tag Inheritance

Tags on blocks, roles, and plays are inherited by child tasks:

- block:
    - name: Install packages
      package: name=nginx
    - name: Start service
      service: name=nginx state=started
  tags: webserver
  # Both tasks get the 'webserver' tag

Common Tag Patterns

# Environment tags
tags: [production, deploy]
# Phase tags
tags: [phase1, install]
# Component tags
tags: [database, postgresql]

# Deploy only database in production
ansible-playbook site.yml --tags "database"
# Run everything except monitoring
ansible-playbook site.yml --skip-tags "monitoring"

FAQ

Do handlers respect tags?

Handlers run when notified, regardless of tags. A tagged task that changes will trigger its handler even if the handler isn't tagged.

Can I use tags in roles?

Yes — tag the role in the playbook, or tag individual tasks within the role. Role-level tags apply to all tasks in that role.

Should I tag every task?

No — tag logical groups. Over-tagging makes playbooks harder to maintain. Use tags for phases (install, configure, deploy) or components (web, db, monitoring).

Basic Tags

- hosts: all
  tasks:
    - name: Install packages
      apt: { name: nginx, state: present }
      tags: [packages]
      become: true
- name: Deploy config
      template: { src: nginx.conf.j2, dest: /etc/nginx/nginx.conf }
      tags: [config]
      become: true
- name: Start service
      service: { name: nginx, state: started }
      tags: [service]
      become: true

Run Specific Tags

# Only run "config" tasks
ansible-playbook site.yml --tags config
# Run multiple tags
ansible-playbook site.yml --tags "packages,config"
# Skip specific tags
ansible-playbook site.yml --skip-tags packages
# List all available tags
ansible-playbook site.yml --list-tags

Tag Roles

- hosts: webservers
  roles:
    - role: webserver
      tags: [web]
    - role: monitoring
      tags: [monitoring]

# Only run webserver role
ansible-playbook site.yml --tags web

Tag Includes

- import_tasks: install.yml
  tags: [install]
- include_tasks: configure.yml
  tags: [configure]

Multiple Tags Per Task

- name: Deploy SSL certificate
  copy:
    src: cert.pem
    dest: /etc/ssl/cert.pem
  tags:
    - ssl
    - security
    - deploy

Special Tags

# 'always' — runs even when filtering by tags
- name: Gather facts
  setup:
  tags: always
# 'never' — only runs when explicitly called
- name: Dangerous cleanup
  shell: rm -rf /tmp/*
  tags: never

# Run 'never' tagged tasks explicitly
ansible-playbook site.yml --tags cleanup,never

Tag Inheritance

# Tags on blocks apply to all tasks inside
- block:
    - apt: { name: nginx }
    - apt: { name: certbot }
    - template: { src: nginx.conf.j2, dest: /etc/nginx/nginx.conf }
  tags: [web]
  become: true

Tagging Strategy

# Recommended: use consistent tag categories
tasks:
  # Component tags
  - apt: { name: nginx }
    tags: [nginx, packages]
# Phase tags
  - template: { src: config.j2, dest: /etc/app.conf }
    tags: [nginx, config]
# Action tags
  - service: { name: nginx, state: restarted }
    tags: [nginx, service, restart]

# All nginx tasks
ansible-playbook site.yml --tags nginx
# Only package installation
ansible-playbook site.yml --tags packages
# Everything except restart
ansible-playbook site.yml --skip-tags restart

Play-Level Tags

- hosts: webservers
  tags: [web]
  tasks:
    - apt: { name: nginx }  # Inherits 'web' tag
- hosts: dbservers
  tags: [database]
  tasks:
    - apt: { name: postgresql }  # Inherits 'database' tag

FAQ

Do tags affect handlers?

Handlers run if notified, regardless of tags. However, if the task that notifies is skipped by tags, the handler won't be triggered.

import_tasks vs include_tasks with tags?

import_tasks: tags apply to individual tasks inside. include_tasks: tags apply to the include statement itself, but you can also pass tags to included tasks.

Can I combine --tags and --skip-tags?

Yes: --tags deploy --skip-tags dangerous runs all 'deploy' tasks except those also tagged 'dangerous'.

Should I tag every task?

No — tag strategically. Common patterns: tag by component (nginx, postgres), by phase (install, configure, deploy), or by action (restart, backup).

Related Articles

• managing Nginx via Ansible • role-based playbook organization in Ansible

See also

• Ansible Tags: Run Specific Tasks in Playbooks (Complete Guide)