community.general.pagerduty module – Create PagerDuty maintenance windows

Note

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

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: example@example.com
    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: example@example.com
    state: running
    service: FOO123
    hours: 4
    desc: deployment
  register: pd_window

- name: Delete the previous maintenance window
  community.general.pagerduty:
    name: companyabc
    user: example@example.com
    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)