State-Aware Execution with Handlers

Lesson 11 of 12 · 8 min · Intermediate

A handler is a special task in Ansible that runs only when another task explicitly notifies it. Handlers prevent unnecessary actions by running only when a genuine change occurs on the system.

Why do we need Handlers?

Suppose a playbook updates a configuration file. If the file changes, the service should restart to apply the new settings. If the file does not change, restarting the service is completely unnecessary.

When to use them

• Restart a service after updating its configuration.
• Reload a service after changing a configuration file.
• Execute a script only after a file has changed.

How a Handler Works & Syntax

The Execution Flow

1. Task Execution A standard task runs (e.g., copying a file).
2. Condition Check If File Changed → Sends a notification to the handler.

If No Change → No notification is sent.
3. Queueing Tasks finish executing in their normal top-to-bottom order.
4. Handler Execution After all tasks successfully complete, the notified Handler executes.

Basic Syntax

tasks:
  - name: Task Name
    module:
      ...
    notify:
      - Handler Name

handlers:
  - name: Handler Name
    module:
      ...

Practical Examples

Basic Handler Execution

We create an employee file using a Jinja2 template. If the file is created or changed, a message is displayed.

employee.j2

Employee Name : {{ empname }}
Age : {{ age }}
Role : {{ role }}

playbook.yml

---
- name: Handler Example
  hosts: localhost
  become: yes

  vars:
    empname: shan
    age: 27
    role: DevOps Engineer

  tasks:
    - name: Create employee file
      template:
        src: employee.j2
        dest: /tmp/employee.txt
      notify:
        - Display Message

  handlers:
    - name: Display Message
      debug:
        msg: "Employee file was updated successfully."

First Run Output

# The template creates the file for the first time.
TASK [Create employee file]
changed

RUNNING HANDLER [Display Message]
ok: Employee file was updated successfully.

Second Run Output

# No variables or content changed.
TASK [Create employee file]
ok

# The handler DOES NOT execute.

Multiple Tasks, One Handler

What happens if multiple tasks notify the exact same handler? If both tasks change their files:

Task 1 → Notify Show Message
Task 2 → Notify Show Message

The handler runs only once after all tasks complete.

multiple_notify.yml

tasks:
  - name: Create employee file
    template:
      src: employee.j2
      dest: /tmp/employee.txt
    notify: Show Message

  - name: Create department file
    copy:
      content: "Department: DevOps"
      dest: /tmp/department.txt
    notify: Show Message

handlers:
  - name: Show Message
    debug:
      msg: "Files have been updated."

Advanced Control & Summary

Running a Handler Immediately

Normally, handlers wait until all tasks finish. If you need a handler to run immediately in the middle of a play, you can force Ansible to execute the queue early using meta: flush_handlers.

flush.yml

tasks:
  - name: Create file
    template:
      src: temp.j2
      dest: /tmp/file.txt
    notify: Show Message

  - meta: flush_handlers

  - name: Check file
    command: cat /tmp/file.txt