How to Use Tags in Ansible Playbook (Examples)

In this blog post, we will show you how to use tags in ansible playbook with examples.

Sometimes, you might want to run specific tasks instead of running an entire playbook file.  This helps to reduce the total playbook execution time, especially when dealing with a large playbook file.

So, what are tags?

Tags in playbooks are pieces of metadata that are attached to tasks in a playbook file. They are referred to when running playbooks and allow you to selectively target certain tasks at runtime. Basically, the instruct Ansible to execute (or not to execute) specific tasks within the playbook file.

Usually, tasks that are skipped have been carried out and hence there is no need to carry them out once again. This way, tags avoid repetition and optimize playbook execution time. They are handy when you want to run certain tasks on demand.

Execute a Specific Task from the Playbook

Let us take an example of a playbook file that executes three tasks as shown. The tags are specified using the tags label at the end of each task.

---
- name: Ansible Tags example
  hosts: localhost
  gather_facts: False
  tasks:
    - name: Hello World tag example
      debug:
        msg: "Hello World!"
      tags:
        - hello

    - name: Welcome to Ansible Tags tag example
      debug:
        msg: "How are you?"
      tags:
        - welcome

    - name: Enjoy tag example
      debug:
        msg: "Enjoy!"
      tags:
        - enjoy

In this playbook, we have three tags: hello, welcome, and enjoy.

$ sudo ansible-playbook /etc/ansible/ansible-01-tags.yml --list-tags

As mentioned earlier, you can use tags to control the execution of Ansible playbooks.  To specify which task to execute use the -t or –tags flag.

In the command below, we are instructing Ansible to execute the first task only which has been tagged as hello.

$ sudo ansible-playbook /etc/ansible/ansible-01-tags.yml --tags hello

Skip Specific Tags in a Playbook

You can also instruct Ansible to skip specific tags using the –skip-tags flag. In doing so, Ansible will run the rest of the tasks in the Playbook file with the exception of the task provided.

In this example, Ansible ignores the last task which is tagged enjoy and executes the rest of the tasks defined in the playbook.

$ sudo ansible-playbook /etc/ansible/ansible-01-tags.yml --skip-tags enjoy

Ensure that a task always (or never) runs

Even as you use tags to determine which tasks to be executed in a playbook file, sometimes, you find that there are tasks that you need to execute.  Take, for example, a playbook that installs Apache on the remote webserver.

The playbook has 3 tasks. It first updates the package lists on the remote host, installs Apache, and restarts it.  However, before installing Apache, it is required to update the package lists or refresh the repositories.

Since refreshing the repositories is a prerequisite, We will tag this task with the always tag.

---
- name: install Apache webserver
  hosts: webserver
  tasks:
    - name: Update and upgrade apt packages
      apt:
        update_cache: yes
      tags:
        - always

    - name: install Apache on Ubuntu
      apt:
        name: apache2
        state: latest
      tags:
        - install_apache

    - name: Restart Apache Webserver
      service:
        name: apache2
        state: restarted
      tags:
        - restart_apache

Without any tags, the playbook runs as expected.

$ sudo ansible-playbook /etc/ansible/ansible-02-tags.yml

If we specify to run a specific task other than the one that is mandatory (which in this case is the first task) Ansible will also execute the task that bears the ‘always’ tag.

In this example, we have instructed Ansible to restart Apache which bears the ‘restart_apache’  tag. However, the ‘update apt repository’ task still runs since it has the ‘always’ tag.

$ sudo ansible-playbook /etc/ansible/ansible-02-tags.yml --tags restart_apache

In the same vein, you can tell Ansible never to run a task, and for this, we use the ‘never‘ tag. This is the exact opposite of the ‘always’ tag.

Back to our playbook. Suppose you don’t want to restart Apache after installing. To achieve this, simply pass the never tag as shown.

- name: Restart Apache Webserver
  service:
    name: apache2
    state: restarted
  tags:
    - restart_apache
    - never

This can also be tagged as follows using the double square brackets:

  tags: [ restart_apache, never ]

When the playbook is executed without any tags, the task will be omitted.

$ sudo ansible-playbook /etc/ansible/ansible-02-tags.yml

From the output, you can see that restart apache task has been skipped.

NOTE:

A task that is tagged ‘never‘ will still run when it is explicitly called in the ansible-playbook command. For example, the task that restarts Apache will still be executed since it has explicitly been defined in the command.

$ sudo ansible-playbook /etc/ansible/ansible-02-tags.yml --tags restart_apache

Wrapping up

Ansible tags are handy and provide the flexibility needed in running Ansible playbooks. You can execute or skip executing specific tasks in a playbook. This provides better control of your playbooks during playbook runtime.

Read Also: How to Use Ansible Vault to Secure Sensitive Data