Ansible: Execute task only when a tag is specified

Ansible 2.5 comes with special tags never and always. Tag never can be used exactly for this purpose. E.g:

tasks:
  - debug: msg='{{ showmevar}}'
    tags: [ 'never', 'debug' ]

In this example, the task will only run when the debug (or never) tag is explicitly requested. [Reference on ansible docs]

Although this is a roundabout solution, it works.

Inside the task list register a variable when normal execution runs. Then, add a when condition that checks that variable to the tagged task.

- shell: /bin/true
  register: normal_task_list

- name: Only run when tag is specified
  shell: /bin/echo "Only running because of specified tag"
  when: normal_task_list is not defined
  tags: specified

I don't have enough reputation to upvote or comment on the answer suggesting the use of command-line variables (--extra-vars), but I have this to add to it:

The caveat to this method is that the play will error and fail if you do not define that extra variable.

You can prevent play failure in the absence of an --extra-vars definition by defining a default value in the playbook itself:

---
- hosts: ...
# ↓↓↓
  vars:
    thorough: false
# ↑↑↑
  tasks:
  - name: apt - install nfs-common only when thorough is true
    when: thorough | bool
    apt:
      cache_valid_time: 86400
      force: yes
      pkg:
        - nfs-common

Overriding via --extra-vars will still work because variables defined on the command line take precedence over all other definitions.

The result is that the play runs without error when thorough is not changed to true on the command line.

You can use Conditionals to protect against accidentally running tasks that would otherwise be executed if you don't specify a tag. The caveat to this method is that the play will error and fail if you do not define that extra variable.

Using the extra-vars argument you can trigger your conditional to be executed.

From ansible-playbook --help:

 -e EXTRA_VARS, --extra-vars=EXTRA_VARS
    set additional variables as key=value or YAML/JSON

Example:

ansible-playbook test.yaml -e "thorough=true"

test.yaml:

...
- name: apt - install nfs-common only when thorough is true
  apt:
    cache_valid_time: 86400
    force: yes
    pkg:
    - nfs-common
  when: thorough | default(False)
...

A perhaps more idiomatic and elegant way is to add a when condition to the task, like such:

tasks:
  - debug: msg='{{ showmevar}}'
    tags: [ 'debug' ]
    when: "'debug' in ansible_run_tags"

This uses the magical variable ansible_run_tags which contains the list of tags supplied through the CLI argument --tags (or synonymously -t) and has the effect of running the above task if and only if the tag debug is given.

It seems this magic variable has been introduced in ansible 2.5

Yes. Running ansible-playbook with the --tags foo flag will ensure that only tasks that are tagged with foo are executed. For example, assume we have a playbook called example.yml:

tasks:

  - yum: name={{ item }} state=installed
    with_items:
       - httpd
       - memcached
    tags:
       - packages

  - name: some other task
    ..
    tags:
      - some other tag

running:

ansible-playbook example.yml --tags "packages"

Will make sure only the yum task is executed.

So actually you don't really need to use tags in when section to conditionally execute a task. Notice that depending on the complexity of your playbooks/roles you might need to use a combination of --tags and --skip-tags to control which tasks are executed. For example, if an include tasks is tagged as 'foo' and some task inside the included playbook is tagged as 'bar' and you run

ansible-playbook --tags "foo"

The internal task (tagged only as 'bar') will be executed. To avoid the execution of all internal tasks tagged as 'bar' you will have to execute the following command

ansible-playbook --tags foo --skip-tags bar

Checking the 'tags' variable isn't working in Ansible 2.1.1.0. See below for the test. I have an other idea to execute task only when a tag is defined, working for both Ansible 1.9.X and 2.X.Y:

- set_fact: foo=true
  tags: bar
- set_fact: foo=false
- name: do something when 'bar' tag is defined
  debug: var=foo
  when: foo
  tags: bar

With that, when running the playbook without any tag, the 'foo' variable will be set to true then to false, so nothing is executed. If you add the 'bar' tag, only the first setting will be applied, so the 'foo' variable will be true, then your task will be executed. Enjoy!

And here's the test about the 'tags' variable in Ansible 2.1.1.0:

Here is the playbook:

- hosts: localhost
  connection: local
  tasks:
    - name: display tags variable
      debug: var=tags
      tags: foo

    - name: do something only when tag 'foo' is provided
      debug: var=tag
      when: tags is defined
      tags: foo

And here is the output:

$ ansible-playbook --version ; ansible-playbook ./test.yml -t foo
ansible-playbook 2.1.1.0
  config file = /home/nootal/projects/ivy/src/ansible/ansible.cfg
  configured module search path = Default w/o overrides

PLAY [localhost] ***************************************************************

TASK [display tags variable] ***************************************************
ok: [localhost] => {
    "tags": "VARIABLE IS NOT DEFINED!"
}

TASK [do something only when tag 'foo' is provided] ****************************

PLAY RECAP *********************************************************************
localhost                  : ok=1    changed=0    unreachable=0    failed=0   

There is a special tag - "never", which will prevent a task from running unless a tag is specifically requested.

tasks:
  - debug: msg='{{ showmevar}}'
    tags: [ 'never', 'debug' ]

The never tag is the correct solution in general, but it won't work in one instance: tags are not supported on meta tasks until Ansible 2.11. In this case we have to fake tag support with a when: conditional and the magic variable ansible_run_tags.

For example, here's a snippet that will list all hosts and end the play early when you say --tags list-hosts. It works with Ansible 2.8 and higher. This is useful if you generated hosts or groups at runtime with add_host or group_by, since that happens too late for --list-hosts.

- pre_tasks:
  - name: List hosts
    assert:
      that: true
      quiet: true
    tags:
      - never
      - list-hosts

  - meta: end_play
    when: "'list-hosts' in ansible_run_tags"

when clause can't evaluate the presence of tags. As a workaround, I use variables and tags together to run tasks specific to that tag/variable.

Ex: Imagine a playbook and inventory

# inventory
[dev]
192.168.1.1

# site.yml
- hosts: dev
  roles:
    - { role: common }

and in common/tasks/main.yml

# roles/common/tasks/main.yaml
- name: Install links
  apt: name=links state=present

- include: uninstall.yml
  when: uninstall_links is defined
  tags:
    - uninstall

# roles/common/tasks/uninstall.yml
- name: Uninstall links
  apt: name=links state=absent

With this approach, you use the tag to select only the tasks in uninstall.yml, but you also need to set 'uninstall_links' variable to something to enable it. So if you run the playbook without any parameters, it will, by default, run the install task. To uninstall, you can set the tag 'uninstall' to your playbook (or cmdline) and MUST set the variable. If you don't set the tag, it will run everything (install and uninstall) in that order, which is good to test the entire process.

How to run everything (it will install and uninstall):

$ ansible-playbook -i inventory site.yml -l dev -s -k -e "uninstall_links=true"

How to run only the 'uninstall' tag on dev group

$ ansible-playbook -i inventory site.yml -l dev -s -k -e "uninstall_links=true" -t uninstall

Therefore, variables and tags could also be in site.yml/inventory files, allowing you to commit into your SCM and record your intention.