Developing Advanced Automation with Red Hat Ansible Automation Platform
Label tasks with tags, run only tasks labeled with specific tags, or start playbook execution at a specific task.
When working with a large or complex playbook, you might consider running only a subset of its plays or tasks.
You can apply tags to specific resources that you want to skip or run.
A tag is a text label on an Ansible resource, such as a play or task.
To tag a resource, use the tags keyword on the resource, followed by a list of the tags to apply.
When running a playbook with ansible-navigator, use the --tags option to filter the playbook and run only specific tagged plays or tasks.
Tags are available for the following resources:
Tag an entire play. Use the
tagsdirective at the play level.
--- - name: Setup web services hosts: webserverstags:- setup...output omitted...
Tag each task. This is one of the most common ways that tags are used.
- name: Ensure that packages are installed ansible.builtin.yum: name: "{{ packages }}" state: installedtags:- installWhen you import a task file in a playbook, you can tag that task. Administrators can then set a global tag for the tasks loaded by the
import_tasksdirective.- name: Import common web services tasks import_tasks: common.yml
tags: -webproxy-webserverTag a role in the
rolessection. All the tasks in the role are associated with this tag. In this example, thedatabasesrole has two tags,productionandstaging.roles: - { role: databases,tags: ['production', 'staging']}Tag a block of tasks. All the tasks in the block are associated with this tag. In this example, you group all httpd-related tasks under the
webservertag.- name: Install packages and start httpd service block: - name: Ensure httpd packages are installed ansible.builtin.yum: name: - httpd - php - git - php-mysqlnd state: present - name: Ensure SELinux allows httpd connections to a remote database ansible.posix.seboolean: name: httpd_can_network_connect_db state: true persistent: true - name: Ensure httpd service is started and enabled ansible.builtin.service: name: httpd state: started enabled: truetags:- webserver
Important
How Ansible applies tags to roles and task files depends on whether the role or task file was imported or included.
When you tag an imported resource, such as a role that uses the roles directive, or a task that uses the ansible.builtin.import_role or ansible.builtin.import_tasks modules, then Ansible applies the tag to all tasks in the imported role or task file.
When you tag an included resource, such as a task that uses the ansible.builtin.include_role or ansible.builtin.include_tasks modules, then Ansible applies the tag to the task itself and only runs tasks in the included role or task file if those tasks also use the same tag or the always tag.
If you plan to include a role or a task file, then you must also tag the tasks in the role or task file.
Use the ansible-navigator command to run tasks with a specific tag, using the --tags option, or skip tasks with a specific tag, using the --skip-tags option.
The following playbook contains two tasks.
The first task is tagged with the webserver tag.
The second task does not have any associated tags.
---
- name: Example play using tagging
hosts:
- servera.lab.example.com
- serverb.lab.example.com
tasks:
- name: httpd is installed
ansible.builtin.yum:
name: httpd
state: latest
tags: webserver
- name: postfix is installed
ansible.builtin.yum:
name: postfix
state: latestTo only run the first task, the --tags argument can be used:
[user@host ~]$ansible-navigator run \>-m stdout main.yml -i inventory --tags webserverPLAY [Example play using tagging] ********************************************* TASK [Gathering Facts] ******************************************************** ok: [serverb.lab.example.com] ok: [servera.lab.example.com] TASK [httpd is installed] ***************************************************** ok: [servera.lab.example.com] ok: [serverb.lab.example.com] PLAY RECAP ******************************************************************** servera.lab.example.com : ok=2 changed=1 unreachable=0 failed=0 ... serverb.lab.example.com : ok=2 changed=0 unreachable=0 failed=0 ...
Because the --tags option was specified, the playbook ran only the task tagged with the webserver tag.
You can use the --skip-tags option to skip tasks with a specific tag and only run the tasks without that tag:
[user@host ~]$ansible-navigator run \>-m stdout main.yml -i inventory --skip-tags webserverPLAY [Example play using tagging] ********************************************* TASK [Gathering Facts] ******************************************************** ok: [serverb.lab.example.com] ok: [servera.lab.example.com] TASK [postfix is installed] *************************************************** ok: [serverb.lab.example.com] ok: [servera.lab.example.com] PLAY RECAP ******************************************************************** servera.lab.example.com : ok=2 changed=1 unreachable=0 failed=0 ... serverb.lab.example.com : ok=2 changed=1 unreachable=0 failed=0 ...
You can associate multiple tags with the --tags and --skip-tags options using a comma-separated list:
[user@host ~]$ansible-navigator run \>-m stdout main.yml -i inventory --tags install,setup
To list all tags that exist in a playbook, pass the --list-tags option to the ansible-navigator command.
For example:
[user@host examples]$ansible-navigator run \>-m stdout playbook.yml -i inventory --list-tagsplaybook: playbook.yml play #1 (webservers): Setup web services TAGS: [setup] TASK TAGS: [setup] play #2 (webservers): Teardown web services TAGS: [teardown] TASK TAGS: [teardown]
Ansible has a special tag that can be assigned in a playbook: always.
A resource tagged always runs every time, even if it does not match the list of tags passed to the --tags option.
The only exception is when it is explicitly skipped, using the --skip-tags always option.
A task that you tag with the never tag does not run, unless you run the playbook with the --tags option set to never or to one of the other tags associated with the task.
There are three additional special tags:
The
taggedtag runs any resource with an explicit tag.The
untaggedtag runs any resource that does not have an explicit tag, and excludes all tagged resources.The
alltag includes all tasks in the play, whether they have a tag or not. This is the default behavior of Ansible.
References
