Ansible Text Message Notifications with Twilio SMS

Ansible Text Message Notifications with Twilio SMS

Nothing puts a damper on a developer’s work day quite like coming back from lunch to find a broken application deployment. But who wants to bring their laptop to lunch with them to check deployment progress? Life would be so much easier if you could just receive a text message on your phone when the deployment completes successfully or if something goes horribly wrong that needs fixing.

Fortunately if you’re using the Ansible configuration management tool as part of your application deployment process there’s a new core notification module called Twilio to send critical deployment updates by text message so you only need your cell phone with you during lunchtime taco stand trips.

Ansible Notification Modules

Ansible is an open source configuration management and application deployment tool. Developers write deployment instructions in files known as playbooks that instruct Ansible to automate installing packages, setting up users, pulling source code from version control and executing many other deployment tasks on remote nodes. Deployments can be completely automated from a single node up to thousands that need provisioning and configuration.

However, even fully automated deployments can run into unpredictable issues. For example, the Internet connection on a remote server could cut out while deploying to it. When something breaks you want to know about it immediately so you can start fixing the problem. That’s where Ansible’s notification modules come in. Notifications alert the appropriate people when there is a deployment issue or something seems out of the ordinary.

There are fifteen core notification modules in Ansible 1.6. Six of those fifteen modules were added since Ansible’s previous 1.5 release in late February. Each notification module makes integrating an external service into a playbook as simple as writing a few lines of YAML. Many of these services, such as Flowdock, Campfire, Hipchat and Slack are great for broadcasting out a message to the whole development team while they are at their computers.

However, a text message is the easiest way to be notified when you’re away from your computer and deployment with Ansible goes wrong. That’s where the new Ansible Twilio core notification module can be useful. The Twilio notification module allows an Ansible playbook to send a text message through the Twilio API.

Let’s walk through an example Ansible deployment playbook to see how to use the Twilio notification module. There is an example playbook repository on GitHub you can follow along with during the post. Note the three tags on the repo. Example step 1 is a simple playbook that uses the get_url module to download a file from GitHub, step 2 shows an implementation of when get_url breaks and has to send a notification about the failure to download a required file and step 3 fixes the issue with the file download and skips over executing the Twilio module because the file download step is successful.

Step 1: Download a Remote File

We’ll start with the first example step tag example-step-1 to show how the example playbook is structured.

There are several files in the base directory that are important:

• ansible-twilio.yml applies the “common” role to all nodes we specify in the hosts file.
• hosts file is set up with localhost as a default for testing purposes. You can specify one or more remote servers here as well.
• requirements.txt file which is for the Python pip installation manager.
• group_vars/all specifies two variables, the URL for the file to download and the destination. For example purposes we’ll download the zipped tarball (.tar.gz extension) for the gh-pages branch of the Full Stack Python open deployment book I wrote.
• roles/common/tasks/main.yml contains the get_url module we’ll use to download the .tar.gz file.

We can kick off the Ansible playbook with the ansible-playbook ansible-twilio.yml command and we’ll see the following successful execution:

Now we have the file .tar.gz downloaded on all nodes specified in our hosts file.

Step 2: Add the Twilio Module to the Playbook

Let’s add the Twilio module to the playbook so we can receive notifications in case the get_url file download fails.

There are a couple of files that need to be modified. First we need to add two modules to the roles/common/tasks/main.yml file. We also add the ignore_errors: yes option to the get_url task so that if the file download is not successful the playbook will not exit immediately upon the failure.

We see in the example-step-2 tag that we now check if the file exists and if it does not, the Twilio module sends a text message notification with the failing URL.

The group_vars/all file also needs a few extra variables so they can be used in the playbook.

Signing up for Twilio to Send Notifications

Before we can execute the enhanced playbook and use the Twilio notifications module you’ll need to sign up for Twilio, purchase a phone number and grab your account credentials from the account details page. If you already have a Twilio account with a phone number you can skip on to the next section.

First sign-up for a free Twilio account.

After signing up Twilio needs quickly verify you’re a human and not a malicious spam bot by either sending you a text message or giving you a voice call.

If you choose the text message verification you’ll receive a message like this one to enter into the sign-up form.

Twilio will assign a random phone number once the sign-up process is complete. You can also search for another number through the Twilio web interface or purchase one programmatically through the API.

Answers to further phone number questions can be found on the phone number FAQ page.

We just need to grab the credentials from the account dashboard or account details page and include them in our environment variables. The set_envs.sh file in example-step-2 includes placeholders for those necessary variables:

Text message away!

We can now re-run the modified playbook with our new number and credentials exported to the environment. Make sure to delete the existing downloaded file that we obtained in step 1 before running this step as otherwise Ansible will assume the get_url module ran successfully. We’ll see the following output:

The phone with the number specified in the alert_number variable should now see a text message detailing the URL which failed to successfully download.

As a last step let’s fix the issue with the URL to show that the Ansible playbook does not send a text message when the file download is successful.

Now when we execute the build script again the .tar.gz file is downloaded and the playbook skips the Twilio text message notification about a failed download.

That’s how you use the new Ansible 1.6 Twilio module to notify you when something important happens with your deployments.

Send me a message at mmakai@twilio.com, on Twitter @mattmakai or GitHub at makaimc with further questions, comments, or improvements to the Twilio notification plugin or examples repository.