Use Ansible Tags to Organise your Plays & Tasks

The Ansible tag documentation does a great job of explaining tags, tag re-used and tag inheritance.  However, I’d like to dive a little deeper to show you just how useful they can be.

To get the most out of this post you’ll need to be familiar with the ways in which you can structure your Playbooks. If you don’t know how they can be structured, or if you need a refresher, I covered this topic in both my The Anatomy of an Ansible Playbook and Ansible Playbook Structure posts.

Playbook Structure

For the purpose of this post, I’m using the following Playbook Layout:

Let’s now go ahead and break down each component of this structure.


As per the Ansible best practices documentation:

In site.yml, we include a playbook that defines our entire infrastructure. Note this is SUPER short, because it’s just including some other playbooks.

We see two things happening in “site.yml”:

  1. The “rtr.yml” and “swh.yml” Playbooks are being included as per the quoted documentation above.
  2. We see a tag being applied to each of the Playbooks.

As mentioned in the Ansible tag documentation, tags are inherited. This means that all Playbooks and Tasks included inside of the “rtr.yml” and “swh.yml” Playbooks will inherit these tags.

rtr.yml & swh.yml

These two Playbook files simply “include” the roles which they pertain to:

Note that an alternative option would be to not tag at the“site.yml” Playbook level and instead tag at the “rtr.yml” and “swh.yml” Playbook role level instead. For example, instead of doing the above, your “rtr.yml” could look like this instead:

As you can see, this affords you more flexibility because your “show” and “configuration” commands will be contained in different directories and will be tagged differently too.

main.yml files

Similar to the Playbook files covered in the previous section, the two “main.yml” files “include” the Task files they pertain to:

Note that this time I have applied applied tags.

Task files

Because the Task files are almost identical, I’ll only cover one from each Playbook – “sh_ip_route.yml” and “sh_mac.yml”.

Bringing it all Together

Now that we’ve got all of our tags applied, let’s see how we can use them to make our lives easier.

Using the --list-tasks  option we can see a list of all of the Tasks contained in the sh_ip_bgp.yml, sh_ip_route.yml, sh_mac.yml and sh_stp.yml files:

Note that as a result of us breaking the Tasks up into roles we can see that they’re neatly displayed in their “routers” and “switches” Playbooks respectively. While this is very useful, it has nothing to to do with tags.

Filtering Tasks

Let’s say we’re interested in looking at the Router tasks only. We can view them by combining the --list-tasks  and  --tags  options:

Excellent, we’ve achieved what we set out to do. However, because our ios_command  and debug  Tasks are named so similarly, having them both listed is redundant. Let’s add the --skip-tags  option to the command above:

And there we have it! A nice, clean list of Router_Tasks .

Running Specific Tasks

The next step is to run the specific Task(s) we’re interested in. To do this we simply use the same commands above but with the --list-tasks  option removed:

While that worked it produced a lot of output. We can avoid this by using the   --skip-tags  option:

Note that the output can be further reduced by specifying the “rtr.yml” Playbook directly instead of “site.yml”:

This is perfectly fine to do because all of the Tasks we’re interested in are contained inside of the role which the “rtr.yml” Playbook has access to.

Knowledge Base

See the Ansible section of my Knowledge Base for more information.

As always, if you have any questions or have a topic that you would like me to discuss, please feel free to post a comment at the bottom of this blog entry, e-mail at, or drop me a message on Twitter (@OzNetNerd).

Note: This website is my personal blog. The opinions expressed in this blog are my own and not those of my employer.