community.general.pagerduty module – Create PagerDuty maintenance windows

Note

This module is part of the community.general collection (version 10.1.0).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install community.general. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: community.general.pagerduty.

Synopsis

  • This module will let you create PagerDuty maintenance windows

Requirements

The below requirements are needed on the host that executes this module.

  • PagerDuty API access

Parameters

Parameter

Comments

desc

string

Short description of maintenance window.

Default: "Created by Ansible"

hours

string

Length of maintenance window in hours.

Default: "1"

minutes

string

Maintenance window in minutes (this is added to the hours).

Default: "0"

name

string

PagerDuty unique subdomain. Obsolete. It is not used with PagerDuty REST v2 API.

requester_id

string

ID of user making the request. Only needed when creating a maintenance_window.

service

aliases: services

list / elements=string

A comma separated list of PagerDuty service IDs.

state

string / required

Create a maintenance window or get a list of ongoing windows.

Choices:

  • "running"

  • "started"

  • "ongoing"

  • "absent"

token

string / required

A pagerduty token, generated on the pagerduty site. It is used for authorization.

user

string

PagerDuty user ID. Obsolete. Please, use token for authorization.

validate_certs

boolean

If false, SSL certificates will not be validated. This should only be used on personally controlled sites using self-signed certificates.

Choices:

  • false

  • true ← (default)

window_id

string

ID of maintenance window. Only needed when absent a maintenance_window.

Attributes

Attribute

Support

Description

check_mode

Support: none

Can run in check_mode and return changed status prediction without modifying target.

diff_mode

Support: none

Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode.

Examples

- name: List ongoing maintenance windows using a token
  community.general.pagerduty:
    name: companyabc
    token: xxxxxxxxxxxxxx
    state: ongoing

- name: Create a 1 hour maintenance window for service FOO123
  community.general.pagerduty:
    name: companyabc
    user: [email protected]
    token: yourtoken
    state: running
    service: FOO123

- name: Create a 5 minute maintenance window for service FOO123
  community.general.pagerduty:
    name: companyabc
    token: xxxxxxxxxxxxxx
    hours: 0
    minutes: 5
    state: running
    service: FOO123


- name: Create a 4 hour maintenance window for service FOO123 with the description "deployment"
  community.general.pagerduty:
    name: companyabc
    user: [email protected]
    state: running
    service: FOO123
    hours: 4
    desc: deployment
  register: pd_window

- name: Delete the previous maintenance window
  community.general.pagerduty:
    name: companyabc
    user: [email protected]
    state: absent
    window_id: '{{ pd_window.result.maintenance_window.id }}'

# Delete a maintenance window from a separate playbook than its creation,
# and if it is the only existing maintenance window
- name: Check
  community.general.pagerduty:
    requester_id: XXXXXXX
    token: yourtoken
    state: ongoing
  register: pd_window

- name: Delete
  community.general.pagerduty:
    requester_id: XXXXXXX
    token: yourtoken
    state: absent
    window_id: "{{ pd_window.result.maintenance_windows[0].id }}"

Authors

  • Andrew Newdigate (@suprememoocow)

  • Dylan Silva (@thaumos)

  • Justin Johns

  • Bruce Pennypacker (@bpennypacker)