PagerDuty integration

The PagerDuty plugin for Backstage requires some steps to be performed in PagerDuty before you start configuring the plugin in Backstage. Follow the steps below to ensure all requirements are in-place.

Warning

PagerDuty plugin for Backstage relies on the Events API v2 integration to send events to PagerDuty.

To setup an integration on a PagerDuty service and generate the necessary authorizations, such as the API token or register an App, you need a PagerDuty Admin role. If you do not have this role, reach out to a Global Admin or Account Owner within your organization to request configuration of this plugin.

Setup PagerDuty

The PagerDuty plugin for Backstage will in essence perform two types of actions.

Will use the Events API v2 to send events to PagerDuty and trigger incidents on a specific service.
Will use the PagerDuty REST API to query for service information that will then be shown in the PagerDuty Card component.

Perform the following steps on PagerDuty before integrating the plugin in Backstage.

Create a service integration for Backstage (optional)

Note

In one the latest releases of the plugin (@pagerduty/backstage-plugin-backend:0.9.0) we introduced a mechanism to automatically create a Backstage integration on every service mapped to a Backstage instance that doesn't have an integration setup yet. This saves admins time setting up the the integration between Backstage entities and PagerDuty services.

You might still want to create integrations yourself in some situations, for instance, if you are using Terraform to configure your PagerDuty services. In that case, the plugin will just pick this information up and add it as an annotation on the entity.

Creating a service integration in PagerDuty is the default mechanism to connect services with alerts coming from third-party tools and platforms. In order to create a service integration you can follow three different approches:

If you are adding your integration to an existing service:
1. From the top menu, select Services.
2. Click the name of the service you want to add the integration to.
3. Go to the Integrations tab and click Add an Integration button.
4. Search for the Backstage integration, select it and click the Add button.
5. An integration will be created and you can see the integration key and the integration endpoint.
Note

On this screen you can update the integration name to something that allows you to easily identify the Backstage instance you are connecting to.
If you are creating a new service for your integration: Follow the instructions in the documentation that shows how to create a service and select Backstage as the Integration Type in step 5.
If you want to automate service creation with Software Template: Follow the steps in Create PagerDuty service with Software Templates.

Once you complete this step you will be able to configure your services in Backstage to create incidents in PagerDuty by using the Events API.

Setup API Authorization

To use PagerDuty REST APIs you need to have either an API Token or a registered Application that will give you the necessary credentials to request a temporary access token. Follow just one of the following sections as they serve the same purpose but in slightly different ways.

Note

The API Token will grant access to all APIs and operations. If this is a security concern, please use Scoped OAuth which is now supported in all PagerDuty supported regions and allows you to specify the APIs and operations that Backstage can leverage. This improves security by limiting the given permissions assigned to the token.

Scoped OAuth is the recommended approach.

Register an Application for Scoped OAuth (recommended)

In order to use Scoped OAuth you need to register an App in PagerDuty. Follow the next steps to register an app, define the necessary permissions and capture the necessary information to generate a temporary access token.

Log int to your PagerDuty account
From the top menu, select Integrations.
Select App Registration from the menu.
Once in the app registration page, select + New App.
Provide a name and description to your app.
Select the OAuth 2.0 check-box, and click Next.
Select Scoped OAuth as the preferred Authorization mechanism.

On permission scope we recommend you to select the following permissions to ensure that the plugin works as expected. Once you select them click on *Register App.

    abilities.read // used in scaffolder only
    analytics.read
    escalation_policies.read
    incidents.read
    oncalls.read
    schedules.read
    services.read
    services.write // used in scaffolder only
    standards.read
    teams.read
    users.read
    vendors.read // used in scaffolder only

Warning

You don't have to assign all the above permissions to your application but not doing so might prevent the plugin from running as expected and you might see some errors on the PagerDuty card.

Copy the Client ID and Client Secret and store them somewhere safe. We will use them later when configuring Backstage.

If you were successful in following the above steps you are ready to move to the Backstage configuration.

Generate a General Access REST API Token

Note

General Access Tokens provide an API token with the full access to the PagerDuty Account by default. Still, you can choose to create API tokens with read-only access by following the action mentioned on step 4.

To create an API Key to use with Backstage you:

Open the PagerDuty console
Navigate to the Integrations > API Access Keys
Click Create new API Key
Enter a Description to help you identify the key later

Note

For added security you may select the Read-only API Key check-box. Current capabilities of this plugin only perform read operations on the API so it is safe to do so.

This might change in the near future when new features are added.
Click Create Key
Copy the key and store it somewhere safe as we will need it later

If you were successful in following the above steps you are ready to move to the Backstage configuration.