Ansible Integration Guide

This integration requires use of our v1 REST API which is currently in a decommissioning period, please contact support to gain access to a v1 REST API key to configure this integration.

For more information about the v1 REST API deprecation, take a look at our FAQ here: https://v2.developer.pagerduty.com/v2/docs/v1-rest-api-decommissioning-faq

We are working with partners to upgrade integrations to use our v2 REST API.

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, and choose an API version. You will also have the option to create the key as Read-only; leaving this box unchecked will create a full access key._int3__API_Keys_-_PagerDuty A note about versioning: API v2.0 is designed to make it easier for new integrations to communicate with PagerDuty. Most existing PagerDuty integrations will require an API v1.0 key. If you have questions on which API version to use, please contact support@pagerduty.com
  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.api__2_
  6. Once created, you will see your key appear in the list of keys on the API Access page, with versioning noted.api__3_
  7. In the top right corner, click on your avatar and select My Profile.
    PDAnsible-ansible-03
  8. 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