Define and Use Handlers in Ansible Playbooks

Docker

Handlers are just like normal tasks in an Ansible playbook but they run only when if the Task contains a "notify" directive. It also indicates that it changed something. These tasks include restarting or reloading services after modifications are made in the configuration files. Let take an example, it is useful for secondary actions that might be required after running a Task.

Here at Ibmi Media, as part of our Server Management Services, we regularly help our Customers to perform related Ansible queries.

In this context, we shall look into method to Define and Use Handlers in Ansible Playbooks.

Ansible Playbook file with a handler for restarting Nginx

To get a firm grasp of the role of handlers in Ansible, we will create a simple playbook file called install_nginx.yml.

The playbook contains a single play that installs the Nginx webserver on a remote Ubuntu node. Right after installation, the notify directive instructs the handler to restart the Nginx service

Take careful note the 'notify' definition matches the name of the handler. As you can see the 'Restart Nginx' definition under the notify directive matches the name of the Handler in the playbook.

Now, let us run the playbook file:

$ ansible-playbook /etc/ansible/install_nginx.yml -K

From the output, you will see that Ansible executed the task first, followed by the handler.

Additionally, you can see that it recorded 2 changes which are actually the installation of Nginx and Restarting of the Nginx service which was carried out by the handler.

The primary task was the installation of Nginx, while the secondary task was restarting the Nginx webserver.

Ansible Playbook file with multiple plays and handlers

Additionally, you can have a scenario where a playbook file contains multiple plays and handlers.

These are the plays we have:

Installing Nginx.
Allowing HTTP traffic across the UFW firewall.

After the plays are executed, the notify directive calls each of the handlers to perform their tasks – restarting Nginx and reloading the UFW firewall.

Here, the secondary tasks performed by the handlers are:

Restarting the Nginx service.
Reloading the firewall.

A handler to restart the Nginx service would look like:

...
  handlers:
    - name: Restart Nginx
      service:
        name: nginx
        state: restarted

To trigger this handler, you'll need to include a notify directive in any task that requires a restart on the Nginx server.

Now let's run the playbook once more:

$ ansible-playbook /etc/ansible/install_nginx.yml -K

Here, we have a total of four tasks. The first two are carried out by the plays and the remaining two are handled by the handlers. You can see that after runtime, the playbook recorded 4 changes which correspond to the number of operations or tasks carried out.