Receive notifications in PagerDuty¶

Staying aware of expiring certificates and unhealthy certificate issuers is critical to protect machine identities and reduce the likelihood of certificate-related outages. Venafi Control Plane allows you to configure such notifications to be sent to PagerDuty so that you can stay aware of potential problems.

PagerDuty is an incident management system used by organizations to track and resolve incidents. Venafi Control Plane can trigger incidents based on the health of monitored resources.

This page walks you through the steps to integrate Venafi Control Plane with PagerDuty and set up these notifications.

Configuration overview¶

Setting up PagerDuty to receive notifications from Venafi Control Plane requires some simple configuration in both the PagerDuty and Venafi Control Plane UIs.

Before you begin¶

Before you begin, ensure you have the following:

Relevant privileges for the PagerDuty dashboard to create services and integrations.
Relevant privileges for the Venafi Control Plane dashboard to add notification providers.
An existing escalation policy in PagerDuty to create a service (or add one when creating a new service). For more information, see the PagerDuty documentation.

Step 1: Create a new service in PagerDuty¶

Before you can receive notifications from Venafi Control Plane you must set up a service in PagerDuty. For more information, see the Services and Integrations page in the PagerDuty documentation for information.

Configuring a service provides you with an integration key that you need when you configure PagerDuty as a notification provider in Venafi Control Plane.

On your PagerDuty dashboard, click Services > Service Directory > New Service.
Name your service, and assign an escalation policy to it.
Select the recommended alert grouping. Otherwise, every alert will create its own incident. This step is optional.
Click Integrations > Events API v2.
Click Create Service, and copy the Integration Key to your clipboard.

Step 2: Add a PagerDuty integration in Venafi Control Plane¶

There are two ways to do this:

Using the Venafi Control Plane UI
Using an API request

Add a PagerDuty integration using the Venafi Control Plane UI¶

In the Venafi Control Plane UI, click Integrations > Notification Providers > New.
Enter a Name for the new integration and select PagerDuty as the Integration Type.
Enter the integration key you copied when creating a service in PagerDuty into the Integration key field and click Save. You see the newly created notification provider in the Notification Providers page.

Add a PagerDuty integration in Venafi Control Plane using an API request¶

This step integrates Venafi Control Plane with PagerDuty. To set up the integration, use the integration key created in the previous step.

Define the name and integrationKey variables (from the steps above). Obtain the tppl-api-key for your environment, then run the following query:

curl --request POST \
  --url https://api.venafi.cloud/graphql \
  --header 'tppl-api-key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "query": "mutation createPagerDutyIntegration($name: String!, $integrationKey: String!) { createPagerDutyIntegration(input: {name: $name, pagerDutyParams: {IntegrationKey: $integrationKey}}) { id } }",
    "operationName": "createPagerDutyIntegration",
    "variables": {
      "name": "name",
      "integrationKey": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    }
  }'

Copy the id from the response and store it as a variable in the GraphQL client called integrationId.

Step 3: Create the routing configuration¶

In this step, you'll define the rules that must be met for a notification to be sent and specify which integration should receive the notifications.

Routing configuration may use CEL expressions to refine event filtering. The sections below outline the available data for building CEL expressions and provide several examples to help you get started.

Best Practice

Use the CEL playground to validate your CEL expressions. Invalid CEL expressions won't trigger notifications.

To use the playground, copy the JSON from the Event details section below into the Input field. Then, copy your CEL expression into the CEL expression field.

Note: On the playground, rename type to _type in both the Input and the CEL expression for the validation to work.

Once you've completed the fields, click Run. Your expression must evaluate to true for notifications to be triggered.

Routing configuration API request¶

The following API request will be used for each routing configuration, regardless of the notification type. You'll replace the following parameters to specify the type of notification you want to receive and what channel you want the notification to be sent to:

name - The name you wish to give to your routing configuration.
eventTypeId - The event type identifier for the event. See Event notification types
advancedFilterExpression - The CEL expression that defines additional conditions that must be satisfied before a notification is sent. See cert-manager unhealthy issuer status for help with building your advanced CEL expression.
integrationID - The id of the integration that the notification should be sent to. The id was generated in the previous step.

API Request¶

curl --request POST \
  --url https://api.venafi.cloud/graphql \
  --header 'tppl-api-key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "query": "mutation CreateNotificationRouter($details: NotificationRouterConfigDetailsInput! $filterConfig: NotificationRouterFilterConfigInput! $integrationConfig: NotificationRouterIntegrationConfigurationInput!) { createNotificationRouter(details: $details filterConfig: $filterConfig integrationConfig: $integrationConfig) { id notificationRouterIntegrationConfig { notificationRouterIntegrationID notificationRouterTemplateID } notificationRouterFilterConfig { advancedFilterExpression } } }",
    "variables": {
      "details": {
        "name": "<your router config name>",
        "eventTypeId": "<event type id>"
      },
      "filterConfig": {
        "advancedFilterExpression": "<CEL-expression>"
      },
      "integrationConfig": {
        "integrationId": "<xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx>"
      }
    }
  }'

Note

This API request validates that the advancedFilterExpression compiles without errors. If it fails it returns an error and the notification router is not created. This validation also happens when updating the notification router.

Have a look at Event notification types for examples for more information on notification types and sample CEL expressions you can use when creating routing configurations.