PagerDuty Notifier

The PagerDuty Notifier posts a message the PagerDuty cloud service.

Message Format

The PagerDuty format is built to provide a readily compatible message. By integrating with PagerDuty, the alarm handler will emit events that create alerts in the PagerDuty console. The message format does not require transformation in PagerDuty, instead it is pre-mapped to the Event API v2.

The following mapping is used:

{
    "routing_key" : "<THE CONFIGURED INTEGRATION KEY>",
    "dedup_key" : "<UNIQUE ALARM IDENTIFIER>",
    "event_action" : "trigger",
    "payload" : {
        "summary" : "<BRIEF DESCRIPTION>",
        "severity": "<REMAPPED SEVERITY>",
        "source"  : "<RESOURCE_TYPE:RESOURCE_ID@NODE_ID>",
        "timestamp" : "<LAST UPDATED>",
        "component" : "<ALARMING RESOURCE ID>",
        "group" : "<ALARMING RESOURCE TYPE>",
        "class" : "<ALARM TYPE>",
        "custom_details" : {
            "dashboard_link": "<URL>",
            "brief_description": "<STRING>",
            "detailed_description": ["<STRING>"],
            "suggested_actions": ["<STRING>"],
            "impact_descriptions": {
                "<TYPE>" : {
                    "title" : "<STRING>",
                    "impacted_dependencies" : ["<STRING>"]
                }
            }
        }
    },
    "links" : [
            {
                "href" : "<DASHBOARD LINK TO ALARM>",
                "text" : "View alarm in Curity dashboard"
            }
    ]
}

The alarm severity is remapped according to the following scheme:

Alarm Severity PagerDuty Severity
CLEAR info
WARNING warning
MINOR error
MAJOR error
CRITICAL critical

Setup PagerDuty

The PagerDuty Alarm Handler requires an integration-key to communicate with the PagerDuty API. Visit the Integration Guide to setup your account.

Make sure to create an Events Integration application.

Testing

PagerDuty has an integration test key that can be used. These are useful for testing the integration and making sure that it works as expected.

../../../_images/pagerduty-setup-1.png

Fig. 40 Integration Test Keys

When you have setup your app, you will be presented with an integration-key and the event URL. The URL looks as follows:

https://events.pagerduty.com/v2/enqueue

The URL should be used when configuring the Alarm Handler in the Curity Identity Server as below:

  • hostname = events.pagerduty.com
  • context = /v2/enqueue
  • port = 443

Note

It is also possible to use the regular Webhook Notifier for integration with PagerDuty by creating a custom Event Transformer. This can be considered if you have specific requirements on what the integration should look like.

Configuration

To configure the PagerDuty alarm handler, an HTTP client needs to be configured, along with the path, host and port to connect to. Any authentication mechanism is configured on the HTTP client, which supports Mutual TLS, Basic Authentication and OAuth Client Credentials.

The alarm handler is configured under /environments/environment/alarms/alarm-handlers/alarm-handler

Parameter Description
pagerduty-notifier/integration-key The integration key received from PagerDuty during app setup
pagerduty-notifier/web-service/hostname Hostname for the pagerduty api (events.pagerduty.com)
pagerduty-notifier/web-service/port Port of the web service (443)
pagerduty-notifier/web-service/context The path on the web service to post to (/v2/enqueue)
pagerduty-notifier/web-service/http-client The configured HTTP client to use (under facilities)
Listing 14 A configured pagerduty handler shown in the CLI
% show environments environment alarms alarm-handlers alarm-handler pd1
pagerduty-notifier {
    web-service {
        hostname    events.pagerduty.com;
        port        443;
        context     /v2/enqueue;
        http-client trustStoreHttpClient;
    }
    integration-key  8f88*****4;
}