Ansible Integration Guide

Ansible is a powerful automation engine that makes systems and applications simple to deploy. No custom scripting or custom code. No agents. All using an automation language that’s easy for anyone to understand and learn. Just get in, get it done, and make some time for other strategic projects.

The PagerDuty Ansible module allows you to create and list ongoing maintenance windows for services on your PagerDuty account. If you are having trouble completing the integration please contact us.

In PagerDuty

If you are using Ansible 1.8 or higher, we highly suggest utilizing an API token and requester ID instead of using a username and password. Please note, you must be an Admin or the Account Owner to get the API token. The steps below will help you locate this information:

  1. From the Configuration menu, select API Access.
    apiaccess-0
  2. On your API Access page, click the +Create New API Key button.apiaccess-1
  3. In the dialog that pops up, you’ll be prompted to enter a Description for your key. You will also have the option to create the key as Read-only; leaving this box unchecked will create a full access key.
  4. Once you have filled in your options, click Create Key.
  5. Once you click Create Key, you will see a dialog displaying your key and confirming the options you filled in on the previous step. Make sure to copy this key into any application that needs it now, as you will not have access to the key after this step. If you lose a key that you created previously and need access to it again, you should remove the key and create a new one. Click Close once you have successfully copied your key.
  6. In the top right corner, click on your avatar and select My Profile.
    PDAnsible-ansible-03
  7. In the URL bar, the last set of characters after the / is your requester ID.
    4-pd-ansible

If you need to find the service ID to create a maintenance window, here’s how you would do so:

  1. Click on the Configuration tab and then click on Services.
    PDansible-ansible-05
  2. Find the service and click on the name.
    PDansible-ansible-06
  3. In the URL, the last set of characters after the / is the service ID.
    6-pd-ansible

In your Ansible playbook

To list the ongoing maintenance windows, you would modify one of the following example tasks:

- name: 'List ongoing maintenance windows using a user/passwd'
  pagerduty: name=acme user=example@example.com passwd=password123 state=ongoing
- name: 'List ongoing maintenance windows using a token'
  pagerduty: name=acme token=xxxxxxxxxxxxxx state=ongoing

To create a maintenance window, you would modify one of the following example tasks:

- name: 'Create a 1 hour maintenance window for service FOO123, using a user/passwd'
  pagerduty: name=acme
             user=example@example.com
             passwd=password123
             state=running
             service=FOO123
- name: 'Create a 5 minute maintenance window for service FOO123, using a token'
  pagerduty: name=acme
             token=xxxxxxxxxxxxxx
             requester_id=P4G5FIY
             hours=0
             minutes=5
             state=running
             service=FOO123
- name: 'Create a 4 hour maintenance window for service FOO123 with the description "deployment"'
  pagerduty: name=acme
             user=example@example.com
             passwd=password123
             state=running
             service=FOO123
             hours=4
             desc=deployment

FAQ

What other actions can I perform with the Ansible PagerDuty module?

At the moment, only listing and creating maintenance windows is available.

Where can I find all the options for the PagerDuty module?

The ansible documentation provides all the options and uses. The PagerDuty module documentation is available at: http://docs.ansible.com/pagerduty_module.html