Skip to main content
Mapagam

Working with Handlers

1. Defining Handlers

Property Description Example
name Unique identifier for the handler restart apache
action Module to execute when handler is triggered service name=apache state=restarted
listen Optional list of events to listen for listen: ['httpd-restart', 'nginx-restart']

Example: Basic Handler Definition

---
- name: Configure Apache
  hosts: webservers
  tasks:
    - name: Update config file
      copy:
        src: /local/apache.conf
        dest: /etc/apache2/apache.conf
      notify: restart apache

  handlers:
    - name: restart apache
      service:
        name: apache
        state: restarted

2. Notifying Handlers

Property Description Example
notify Triggers a handler to run after a task completes notify: restart service
handlers Defined tasks that are executed only when notified 
- name: restart service
  service:
    name: nginx
    state: restarted

Example: Notifying a Handler

- name: Update configuration file
  template:
    src: nginx.conf.j2
    dest: /etc/nginx/nginx.conf
  notify: restart nginx

- name: Restart Nginx
  service:
    name: nginx
    state: restarted
  when: ansible_facts.services.nginx is defined
Note: Handlers are executed once per play, after all tasks have completed.

3. Executing Handlers Immediately

Property Description Example
notify Trigger a handler from a task 
- name: Restart service
  command: systemctl restart myservice
  notify: restart web server
handler Handler definition in handlers/main.yml 
- name: restart web server
  systemd:
    name: nginx
    state: restarted

Example: Notify Handler from Task

- name: Update configuration file
  template:
    src: nginx.conf.j2
    dest: /etc/nginx/nginx.conf
  notify: reload nginx

Example: Handler Definition

- name: reload nginx
  systemd:
    name: nginx
    state: reloaded
Note: Handlers are executed once per play, after all tasks have completed.
Warning: Handlers will not run if the task that notifies them is skipped or fails.

4. Listening to Topics

Property Description Example
listen Specifies the topic(s) that a handler should listen to. This allows handlers to be triggered by events or messages published to specific topics. listen: ["topic1", "topic2"]
name Unique identifier for the handler. name: "handle_error"
event Event type that triggers the handler (e.g., message, error). event: "message"

Example: Listening to a Topic

- name: Listen to error topic
  ansible.builtin.handler:
    listen:
      - "error"
    name: handle_error
    event: "message"
Note: Handlers that listen to topics are typically used in conjunction with messaging systems or event-driven architectures.

5. Forcing Handler Execution

Option Description Usage
notify Triggers handlers after a task completes notify: restart_service
always_run Ensures handler runs even if task is skipped always_run: true
force_handlers Forces handler execution regardless of changes force_handlers: true

Example: Using notify to trigger handler

tasks:
  - name: Update configuration file
    copy:
      src: config.conf
      dest: /etc/app/config.conf
    notify: restart_service

handlers:
  - name: restart_service
    systemd:
      name: app.service
      state: restarted

Example: Forcing handler execution with always_run

tasks:
  - name: Update app settings
    template:
      src: settings.j2
      dest: /etc/app/settings.conf
    always_run: true
    notify: reload_app

handlers:
  - name: reload_app
    command: systemctl reload app.service

6. Controlling Handler Order

Property Description Default Notes
listen Defines the event that triggers the handler None Can be any valid event name or list of events
notify Specifies which handler(s) to run when a task changes None Must match handler name defined in handlers section
when Conditional logic to determine if handler runs True Same syntax as task-level when conditions

Example: Using listen and notify

---
- name: Configure web server
  hosts: webservers
  tasks:
    - name: Update configuration file
      copy:
        src: web.conf
        dest: /etc/web.conf
      notify: restart web server

    - name: Update application code
      git:
        repo: https://github.com/example/app.git
        dest: /opt/app
      notify: restart web server

  handlers:
    - name: restart web server
      listen: restart web server
      systemd:
        name: nginx
        state: restarted
Note: Handlers are executed once per play, after all tasks have completed. The order of handler execution is determined by the notify declarations in tasks and their placement in the handlers list.

Handler Execution Rules

  • Handlers run once per play, after all tasks complete
  • Handlers execute in the order they appear in the handlers list
  • Multiple tasks can notify the same handler
  • Handlers only run if a task has changed (or changed_when is set)

7. Using Handler Names

Property Description Usage
name Unique identifier for the handler Used to reference the handler in tasks or other handlers
notify Task directive to trigger a handler Used in tasks to indicate that a handler should be run if the task changes

Example: Using Handler Names

---
- name: Configure web server
  hosts: webservers
  tasks:
    - name: Update configuration file
      template:
        src: web.conf.j2
        dest: /etc/web.conf
      notify: restart web service

    - name: Update application code
      git:
        repo: https://github.com/example/app.git
        dest: /opt/app
      notify: restart web service

  handlers:
    - name: restart web service
      systemd:
        name: nginx
        state: restarted

8. Notifying Multiple Handlers

Handler Notification Notes
notify handler1, handler2 Comma-separated list of handlers to notify

Example: Notifying Multiple Handlers

tasks:
  - name: Restart web server
    command: systemctl restart nginx
    notify:
      - restart_web_server
      - reload_firewall

  - name: Update configuration
    template:
      src: nginx.conf.j2
      dest: /etc/nginx/nginx.conf
    notify:
      - restart_web_server
      - reload_firewall
Note: Handlers are notified only once per play, even if multiple tasks notify them.

9. Preventing Handler Execution

Option Values Notes
notify handler_name Handler to notify when a task changes state
listen handler_name Handler to listen for events from other handlers
when condition Condition to evaluate before running handler

Example: Using when to conditionally execute handler

- name: Restart service only if config changed
  command: echo "config updated"
  notify: restart_service
  when: config_changed

- name: Restart service
  systemd:
    name: myservice
    state: restarted
  listen: restart_service
Note: Handlers are executed once per play, not once per host.
Warning: Using when on a handler itself will not prevent it from being triggered by notify.

10. Importing Handlers

Method Description Example
import_handlers Imports handlers from another file or role 
- name: Import handlers from a role
  import_handlers:
    name: myrole.handlers
include_handlers Includes handlers from a file or role 
- name: Include handlers from a file
  include_handlers:
    file: common/handlers.yml

Example: Importing Handlers from a Role

- name: Import handlers from a role
  import_handlers:
    name: myrole.handlers

Example: Including Handlers from a File

- name: Include handlers from a file
  include_handlers:
    file: common/handlers.yml

11. Including Handlers

Property Description Example
include_tasks Includes a set of tasks from another file 
- name: Include handlers
  include_tasks: handlers/main.yml
import_tasks Imports a set of tasks from another file at parse time 
- name: Import handlers
  import_tasks: handlers/main.yml

Example: Including Handlers from a File

- name: Include handlers from a file
  include_tasks: handlers/main.yml
Note: include_tasks is evaluated at runtime, while import_tasks is evaluated at parse time.

Was this article helpful?

Related Cheat Sheets