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. This guide assumes you have a PagerDuty application ready and will add a new Service Integration

Visit the Services -> Service Directory page and click the service that you want to add the alarm integration with.

On the Integrations tab click +Add another integration and search for and select the Curity Identity Server integration.

../../../_images/pd-add-integration.png

Fig. 14 Add the Curity Identity Server integration

This adds a new integration to the list in your service. Click the down arrow to expand the service and see the integration keys.

../../../_images/pd-integration-keys.png

Fig. 15 Get the keys

When the integration is setup in PagerDuty, you have the integration-key and the integration-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 4 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 defaultHttpClient;
    }
    integration-key  8f88*****4;
}