Ansible Tags

By default, a playbook runs every task, top to bottom, every time. Our website playbook installs httpd, copies index.html and starts the service, and it does all three even when you only changed one line of HTML. Two features give you more control:

• Handlers run a task only when another task actually changed something
• Tags let you pick which tasks run, from the command line

This lesson builds both into the website playbook.

Start from the variables playbook

sudo su - ansible
cat vars.yml
vi handlers.yml

Paste the content of vars.yml and change it like this:

---
- hosts: webservers
  become: true
  vars:
    package_name: httpd
  tasks:
    - name: httpd server installation
      yum:
        name: "{{ package_name }}"
        state: latest
      tags:
        - install
    - name: copy index.html
      copy:
        src: index.html
        dest: /var/www/html/index.html
      tags:
        - copy
      notify:
        - start httpd server
  handlers:
    - name: start httpd server
      service:
        name: "{{ package_name }}"
        state: started
...

What changed compared to vars.yml:

Indentation matters a lot here. tags and notify belong to the task, so they line up with name and copy of that task. handlers belongs to the play, so it lines up with hosts, vars and tasks.

Handlers: run only when something changed

ansible-playbook handlers.yml --syntax-check
ansible-playbook handlers.yml

TASK [httpd server installation] **********************************************
ok: [172.31.9.250]

TASK [copy index.html] *********************************************************
ok: [172.31.9.250]

PLAY RECAP *********************************************************************
172.31.9.250   : ok=3    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

The handler did not run at all. index.html on the server is already identical to the one on the control node, so the copy task reported ok, and a task that changes nothing notifies nobody.

Now change the website:

vi index.html

<h1> Telusko DevOps Learning! </h1>
<h2> Visit courses.telusko.com </h2>

Run the playbook again:

TASK [copy index.html] *********************************************************
changed: [172.31.9.250]

RUNNING HANDLER [start httpd server] *******************************************
ok: [172.31.9.250]

PLAY RECAP *********************************************************************
172.31.9.250   : ok=4    changed=1    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

This time the copy reported changed, so the handler ran (RUNNING HANDLER). Refresh the browser and the new line is there.

How handlers behave, according to the official docs:

• A handler runs only if a task that notifies it reports changed
• Handlers run after all the tasks in the play have finished, not immediately after the notifying task
• If several tasks notify the same handler, it still runs only once
• notify uses the handler's name, so handler names must be unique
• If a later task fails, notified handlers do not run, unless you use --force-handlers

  tasks:
    - name: Deploy Apache config
      ansible.builtin.copy:
        src: httpd.conf
        dest: /etc/httpd/conf/httpd.conf
      notify: Restart httpd

  handlers:
    - name: Restart httpd
      ansible.builtin.service:
        name: httpd
        state: restarted

notify accepts a single name (as here) or a list of names (as in handlers.yml).

Tags: choose which tasks run

The lecture adds the tags but does not run them, so let's use them. Without any tag option, every task runs, just like before. With --tags, only the tasks carrying one of those tags run:

ansible-playbook handlers.yml --tags copy

TASK [Gathering Facts] *********************************************************
ok: [172.31.9.250]

TASK [copy index.html] *********************************************************
ok: [172.31.9.250]

The install task is not even shown: it was skipped because it does not have the copy tag. This is exactly what you want when you only changed the website: no time spent checking packages. --skip-tags does the opposite, it runs everything except the tagged tasks:

ansible-playbook handlers.yml --skip-tags install

ansible-playbook handlers.yml --list-tags

playbook: handlers.yml

  play #1 (webservers): webservers	TAGS: []
      TASK TAGS: [copy, install]

A few rules worth knowing:

• Tasks without a tag are skipped when you use --tags. Tag every task you might want to run on its own
• If a task matches both --tags and --skip-tags, skipping wins
• Two special tags: a task tagged always runs even with --tags (unless you skip always), and a task tagged never runs only when you ask for it by name with --tags
• Handlers ignore tags. If a task that ran notifies a handler, the handler runs, whatever tags you selected

Try It Yourself

1. Run handlers.yml twice without changing anything and confirm the handler never runs.
2. Change index.html, then run with --skip-tags copy. Did the handler run? Why not?
3. Add a third task that creates /var/www/html/health.html with ansible.builtin.copy and content: "OK", tag it health, and run only that task with --tags health.
4. Add a debug task tagged never and show that it runs only with --tags never.
5. Rewrite the handler as Restart httpd with state: restarted, deploy a small change to /etc/httpd/conf.d/telusko.conf, and watch the restart happen only when the file changes.

Official references

• Handlers: running operations on change
• Tags
• ansible.builtin.service module

Written By: Shramik Masti