How To Define and Use Handlers in Ansible Playbooks

Published on April 15, 2021

Developer Advocate

How To Define and Use Handlers in Ansible Playbooks

In a nutshell, handlers are special tasks that only get executed when triggered via the notify directive. Handlers are executed at the end of the play, once all tasks are finished.

In Ansible, handlers are typically used to start, reload, restart, and stop services. If your playbook involves changing configuration files, there is a high chance that you’ll need to restart a service so that the changes take effect. In this case, you’ll need to define a handler for that service and include the notify directive in any tasks that require that service handler.

In a previous section of this series, you’ve seen how to use a template to replace the default Nginx page with a custom HTML landing page. In practice, when setting up your Nginx web server, you’re most likely going to include new server block files in your sites-available directory, create symbolic links, or change settings that require a server reload or restart.

Considering such a scenario, this is how a handler to restart the Nginx service would look like:

    - name: Restart Nginx
        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.

The following playbook replaces the default document root in Nginx’s configuration file using the built-in Ansible module replace. This module looks for patterns in a file based on a regular expression defined by regexp, and then replaces any matches found with the content defined by replace. The task then sends a notification to the Restart Nginx handler for a restart as soon as possible. What that means is, it doesn’t matter how many times you trigger the restart, it will only happen when all tasks are already finished executing and the handlers start running. Additionally, when no matches are found, no changes are made to the system, and for that reason the handler is not triggered.

Create a new file called playbook-12.yml in your ansible-practice directory:

  1. nano ~/ansible-practice/playbook-12.yml

Add the following lines to the new playbook file:

- hosts: all
  become: yes
    page_title: My Second Landing Page
    page_description: This is my second landing page description.
    doc_root: /var/www/mypage

    - name: Install Nginx
        name: nginx
        state: latest

    - name: Make sure new doc root exists
        path: "{{ doc_root }}"
        state: directory
        mode: '0755'

    - name: Apply Page Template
        src: files/landing-page.html.j2
        dest: "{{ doc_root }}/index.html"

    - name: Replace document root on default Nginx configuration
        path: /etc/nginx/sites-available/default
        regexp: '(\s+)root /var/www/html;(\s+.*)?$'
        replace: \g<1>root {{ doc_root }};\g<2>
      notify: Restart Nginx

    - name: Allow all access to tcp port 80
        rule: allow
        port: '80'
        proto: tcp

    - name: Restart Nginx
        name: nginx
        state: restarted

Save and close the file when you’re done.

One important thing to keep in mind when using handlers is that they are only triggered when the task that defines the notify trigger causes a change in the server. Taking this playbook into account, the first time it runs the replace task it will change the Nginx configuration file and thus the restart will run. In subsequent executions, however, since the string to be replaced is not present in the file anymore, the task won’t cause any changes and won’t trigger the handler execution.

Remember to provide the -K option if you run this playbook, since it requires sudo permissions:

  1. ansible-playbook -i inventory playbook-12.yml -u sammy -K
BECOME password: PLAY [all] ********************************************************************************************** TASK [Gathering Facts] ********************************************************************************** ok: [] TASK [Install Nginx] ************************************************************************************ ok: [] TASK [Make sure new doc root exists] ******************************************************************** changed: [] TASK [Apply Page Template] ****************************************************************************** changed: [] TASK [Replace document root on default Nginx configuration] ********************************************* changed: [] TASK [Allow all access to tcp port 80] ****************************************************************** ok: [] RUNNING HANDLER [Restart Nginx] ************************************************************************* changed: [] PLAY RECAP ********************************************************************************************** : ok=7 changed=4 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0

If you look at the output, you’ll see the “Restart Nginx” handler being executed just before the end of the play. If you go to your browser and access the server’s IP address now, you’ll see the following page:

Screenshot showing the new landing page after update

In the next and final part of this series, we’ll connect all the dots and put together a playbook that automates setting up a remote Nginx server to host a static HTML website.

Thanks for learning with the DigitalOcean Community. Check out our offerings for compute, storage, networking, and managed databases.

Learn more about our products

Tutorial Series: How To Write Ansible Playbooks

Ansible is a modern configuration management tool that doesn’t require the use of an agent software on remote nodes, using only SSH and Python to communicate and execute commands on managed servers. This series will walk you through the main Ansible features that you can use to write playbooks for server automation. At the end, we’ll see a practical example of how to create a playbook to automate setting up a remote Nginx web server and deploy a static HTML website to it.

About the authors
Default avatar

Developer Advocate

Dev/Ops passionate about open source, PHP, and Linux.

Still looking for an answer?

Ask a questionSearch for more help

Was this helpful?
Leave a comment

This textbox defaults to using Markdown to format your answer.

You can type !ref in this text area to quickly search our full set of tutorials, documentation & marketplace offerings and insert the link!

Try DigitalOcean for free

Click below to sign up and get $200 of credit to try our products over 60 days!

Sign up

Join the Tech Talk
Success! Thank you! Please check your email for further details.

Please complete your information!

Featured on Community

Get our biweekly newsletter

Sign up for Infrastructure as a Newsletter.

Hollie's Hub for Good

Working on improving health and education, reducing inequality, and spurring economic growth? We'd like to help.

Become a contributor

Get paid to write technical tutorials and select a tech-focused charity to receive a matching donation.

Welcome to the developer cloud

DigitalOcean makes it simple to launch in the cloud and scale up as you grow — whether you're running one virtual machine or ten thousand.

Learn more
DigitalOcean Cloud Control Panel