community.general.pagerduty_alert module – Trigger, acknowledge or resolve PagerDuty incidents

Note

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

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_alert.

Synopsis

  • This module will let you trigger, acknowledge or resolve a PagerDuty incident by sending events

Aliases: monitoring.pagerduty_alert

Requirements

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

  • PagerDuty API access

Parameters

Parameter

Comments

api_key

string

The pagerduty API key (readonly access), generated on the pagerduty site.

Required if api_version=v1.

api_version

string

added in community.general 7.4.0

The API version we want to use to run the module.

V1 is more limited with option we can provide to trigger incident.

V2 has more variables for example, severity, source, custom_details, etc.

Choices:

  • "v1" ← (default)

  • "v2"

client

string

The name of the monitoring client that is triggering this event.

client_url

string

The URL of the monitoring client that is triggering this event.

component

string

added in community.general 7.4.0

Component of the source machine that is responsible for the event, for example mysql or eth0.

custom_details

dictionary

added in community.general 7.4.0

Additional details about the event and affected system.

A dictionary with custom keys and values.

desc

string

For state=triggered - Required. Short description of the problem that led to this trigger. This field (or a truncated version) will be used when generating phone calls, SMS messages and alert emails. It will also appear on the incidents tables in the PagerDuty UI. The maximum length is 1024 characters.

For state=acknowledged or state=resolved - Text that will appear in the incident’s log associated with this event.

Default: "Created via Ansible"

incident_class

string

added in community.general 7.4.0

The class/type of the event, for example ping failure or cpu load.

incident_key

string

Identifies the incident to which this state should be applied.

For state=triggered - If there’s no open (i.e. unresolved) incident with this key, a new one will be created. If there’s already an open incident with a matching key, this event will be appended to that incident’s log. The event key provides an easy way to ‘de-dup’ problem reports. If no incident_key is provided, then it will be generated by PagerDuty.

For state=acknowledged or state=resolved - This should be the incident_key you received back when the incident was first opened by a trigger event. Acknowledge events referencing resolved or nonexistent incidents will be discarded.

integration_key

string

The GUID of one of your ‘Generic API’ services.

This is the ‘integration key’ listed on a ‘Integrations’ tab of PagerDuty service.

link_text

string

added in community.general 7.4.0

A short description of the link_url.

string

added in community.general 7.4.0

Relevant link url to the alert. For example, the website or the job link.

name

string

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

service_id

string

ID of PagerDuty service when incidents will be triggered, acknowledged or resolved.

Required if api_version=v1.

service_key

string

The GUID of one of your ‘Generic API’ services. Obsolete. Please use integration_key.

severity

string

added in community.general 7.4.0

The perceived severity of the status the event is describing with respect to the affected system.

Required in case of state=trigger and api_version=v2.

Choices:

  • "critical" ← (default)

  • "warning"

  • "error"

  • "info"

source

string

added in community.general 7.4.0

The unique location of the affected system, preferably a hostname or FQDN.

Required in case of state=trigger and api_version=v2.

state

string / required

Type of event to be sent.

Choices:

  • "triggered"

  • "acknowledged"

  • "resolved"

Attributes

Attribute

Support

Description

check_mode

Support: full

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: Trigger an incident with just the basic options
  community.general.pagerduty_alert:
    name: companyabc
    integration_key: xxx
    api_key: yourapikey
    service_id: PDservice
    state: triggered
    desc: problem that led to this trigger

- name: Trigger an incident with more options
  community.general.pagerduty_alert:
    integration_key: xxx
    api_key: yourapikey
    service_id: PDservice
    state: triggered
    desc: problem that led to this trigger
    incident_key: somekey
    client: Sample Monitoring Service
    client_url: http://service.example.com

- name: Acknowledge an incident based on incident_key
  community.general.pagerduty_alert:
    integration_key: xxx
    api_key: yourapikey
    service_id: PDservice
    state: acknowledged
    incident_key: somekey
    desc: "some text for incident's log"

- name: Resolve an incident based on incident_key
  community.general.pagerduty_alert:
    integration_key: xxx
    api_key: yourapikey
    service_id: PDservice
    state: resolved
    incident_key: somekey
    desc: "some text for incident's log"

- name: Trigger an v2 incident with just the basic options
  community.general.pagerduty_alert:
    integration_key: xxx
    api_version: v2
    source: My Ansible Script
    state: triggered
    desc: problem that led to this trigger

- name: Trigger an v2 incident with more options
  community.general.pagerduty_alert:
    integration_key: xxx
    api_version: v2
    source: My Ansible Script
    state: triggered
    desc: problem that led to this trigger
    incident_key: somekey
    client: Sample Monitoring Service
    client_url: http://service.example.com
    component: mysql
    incident_class: ping failure
    link_url: https://pagerduty.com
    link_text: PagerDuty

- name: Acknowledge an incident based on incident_key using v2
  community.general.pagerduty_alert:
    api_version: v2
    integration_key: xxx
    incident_key: somekey
    state: acknowledged

- name: Resolve an incident based on incident_key
  community.general.pagerduty_alert:
    api_version: v2
    integration_key: xxx
    incident_key: somekey
    state: resolved

Authors

  • Amanpreet Singh (@ApsOps)

  • Xiao Shen (@xshen1)