@pagerduty/backstage-plugin 0.7.1 → 0.7.2-next.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +14 -231
- package/package.json +21 -16
package/README.md
CHANGED
|
@@ -4,250 +4,33 @@
|
|
|
4
4
|
[](https://badge.fury.io/js/@pagerduty%2Fbackstage-plugin)
|
|
5
5
|
[](https://opensource.org/licenses/Apache-2.0)
|
|
6
6
|
|
|
7
|
-
**
|
|
7
|
+
**Bring the power of PagerDuty to Backstage!**
|
|
8
|
+
The PagerDuty plugin reduces the cognitive load on developers responsible for maintaining services in production. Instead of having to go to PagerDuty's console, you can now access the necessary information directly within Backstage. This includes finding active incidents or opening a new incident, reviewing recent changes made to the service, and checking who is on-call.
|
|
8
9
|
|
|
9
|
-
##
|
|
10
|
+
## Features
|
|
10
11
|
|
|
11
|
-
-
|
|
12
|
-
-
|
|
13
|
-
-
|
|
12
|
+
- **[Trigger New Incident](<https://pagerduty.github.io/backstage-plugin-docs/capabilities/#trigger-an-incident-for-a-service>)** - Easily create new incidents for your service directly from Backstage. This feature saves time and reduces the need for context switching.
|
|
13
|
+
- **[See Active Incidents](<https://pagerduty.github.io/backstage-plugin-docs/capabilities/#view-any-open-incidents>)** - View all active incidents for a service directly in Backstage.
|
|
14
|
+
- **[Check for Recent Changes](<https://pagerduty.github.io/backstage-plugin-docs/capabilities/#view-change-events-associated-to-a-service>)** - Identify recent changes that may be the root cause of potential issues with your service.
|
|
15
|
+
- **[Identify On-Call Personnel](<https://pagerduty.github.io/backstage-plugin-docs/capabilities/#see-and-contact-on-call-staff>)** - Quickly determine who is responsible for a failing service and resolve the incident as quickly as possible. This feature allows companies to spend more time solving problems rather than determining who should solve them.
|
|
14
16
|
|
|
15
|
-
##
|
|
17
|
+
## Getting Started
|
|
16
18
|
|
|
17
|
-
|
|
18
|
-
- Incidents can be manually triggered via the plugin with a user-provided description, which will in turn notify the current on-call responders. Alternatively, the plugin can be configured with an optional `readOnly` property to suppress the ability to trigger incidents from the plugin.
|
|
19
|
-
- **Note:** This feature is only available when providing the *`pagerduty.com/integration-key`* annotation.
|
|
20
|
-
- Change events will be displayed in a separate tab. If the change event payload has additional links, only the first link will be rendered.
|
|
19
|
+
Find the complete project's documentation [here](https://pagerduty.github.io/backstage-plugin-docs/).
|
|
21
20
|
|
|
22
|
-
|
|
21
|
+
### Installation
|
|
23
22
|
|
|
24
|
-
|
|
23
|
+
The installation of the PagerDuty plugin for Backstage is done with *yarn* as all other plugins in Backstage. This plugin follows a modular approach which means that every individual component will be a separate package (e.g. frontend, backend, common). In this case, you are installing a **frontend plugin**.
|
|
25
24
|
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
### View any open incidents
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
### Email link, and view contact information for staff on call
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
### Trigger an incident for a service
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
## Integration Walk-through
|
|
43
|
-
|
|
44
|
-
### In PagerDuty
|
|
45
|
-
|
|
46
|
-
#### Integrating With a PagerDuty Service
|
|
47
|
-
|
|
48
|
-
1. From the **Configuration** menu, select **Services**.
|
|
49
|
-
2. There are two ways to add an integration to a service:
|
|
50
|
-
- **If you are adding your integration to an existing service**: Click the **name** of the service you want to add the integration to. Then, select the **Integrations** tab and click the **New Integration** button.
|
|
51
|
-
- **If you are creating a new service for your integration**: Please read the documentation in section [Configuring Services and Integrations](https://support.pagerduty.com/docs/services-and-integrations#section-configuring-services-and-integrations) and follow the steps outlined in the [Create a Service](https://support.pagerduty.com/docs/services-and-integrations#create-a-service) section, selecting **Backstage** as the **Integration Type** in step 5. Continue with the [*"In Backstage"*](https://github.com/PagerDuty/backstage-plugin?tab=readme-ov-file#in-backstage) section (below) once you have finished these steps.
|
|
52
|
-
3. Enter an **Integration Name** in the format `monitoring-tool-service-name` (e.g. `Backstage-Shopping-Cart`) and select **Backstage** from the Integration Type menu.
|
|
53
|
-
4. Click the **Add Integration** button to save your new integration. You will be redirected to the Integrations tab for your service.
|
|
54
|
-
5. An **Integration Key** will be generated on this screen. Keep this key saved in a safe place, as it will be used when you configure the integration with **Backstage** in the next section.
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
### In Backstage
|
|
58
|
-
|
|
59
|
-
#### Install the plugin
|
|
60
|
-
|
|
61
|
-
The file paths mentioned in the following steps are relative to your app's root directory — for example, the directory created by following the [Getting Started](https://backstage.io/docs/getting-started/) guide and creating your app with `npx @backstage/create-app`.
|
|
62
|
-
|
|
63
|
-
First, from your Backstage root directory, install the PagerDuty plugin via CLI:
|
|
25
|
+
To install this plugin run the following command from the Backstage root folder.
|
|
64
26
|
|
|
65
27
|
```bash
|
|
66
28
|
yarn add --cwd packages/app @pagerduty/backstage-plugin
|
|
67
29
|
```
|
|
68
30
|
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
Add the following imports to the top of the file:
|
|
72
|
-
|
|
73
|
-
```ts
|
|
74
|
-
import {
|
|
75
|
-
isPluginApplicableToEntity as isPagerDutyAvailable,
|
|
76
|
-
EntityPagerDutyCard,
|
|
77
|
-
} from '@pagerduty/backstage-plugin';
|
|
78
|
-
```
|
|
79
|
-
|
|
80
|
-
Find `const overviewContent` in `EntityPage.tsx`, and add the following snippet inside the outermost `Grid` defined there, just before the closing `</Grid>` tag:
|
|
81
|
-
|
|
82
|
-
```ts
|
|
83
|
-
<EntitySwitch>
|
|
84
|
-
<EntitySwitch.Case if={isPagerDutyAvailable}>
|
|
85
|
-
<Grid item md={6}>
|
|
86
|
-
<EntityPagerDutyCard />
|
|
87
|
-
</Grid>
|
|
88
|
-
</EntitySwitch.Case>
|
|
89
|
-
</EntitySwitch>
|
|
90
|
-
```
|
|
91
|
-
|
|
92
|
-
When you're done, the `overviewContent` definition should look something like this:
|
|
93
|
-
|
|
94
|
-
```ts
|
|
95
|
-
const overviewContent = (
|
|
96
|
-
<Grid ...>
|
|
97
|
-
...
|
|
98
|
-
<EntitySwitch>
|
|
99
|
-
<EntitySwitch.Case if={isPagerDutyAvailable}>
|
|
100
|
-
<Grid item md={6}>
|
|
101
|
-
<EntityPagerDutyCard />
|
|
102
|
-
</Grid>
|
|
103
|
-
</EntitySwitch.Case>
|
|
104
|
-
</EntitySwitch>
|
|
105
|
-
</Grid>
|
|
106
|
-
);
|
|
107
|
-
```
|
|
108
|
-
|
|
109
|
-
#### Configure the plugin
|
|
110
|
-
|
|
111
|
-
First, [annotate](https://backstage.io/docs/features/software-catalog/descriptor-format#annotations-optional) the appropriate entity with the PagerDuty integration key in its `.yaml` configuration file:
|
|
112
|
-
|
|
113
|
-
```yaml
|
|
114
|
-
annotations:
|
|
115
|
-
pagerduty.com/integration-key: [INTEGRATION_KEY]
|
|
116
|
-
```
|
|
117
|
-
|
|
118
|
-
#### The homepage component
|
|
119
|
-
|
|
120
|
-
You may also add the component to the homepage of Backstage. Edit the `HomePage.tsx` file, import `PagerDutyHomepageCard` and add it to the home page. e.g.
|
|
121
|
-
|
|
122
|
-
```typescript jsx
|
|
123
|
-
...
|
|
124
|
-
export const homePage = (
|
|
125
|
-
<Page themeId="home">
|
|
126
|
-
...
|
|
127
|
-
<Content>
|
|
128
|
-
<CustomHomepageGrid config={defaultConfig}>
|
|
129
|
-
...
|
|
130
|
-
<PagerDutyHomepageCard
|
|
131
|
-
name="My Service"
|
|
132
|
-
serviceId="<service id>"
|
|
133
|
-
integrationKey="<integration key>"
|
|
134
|
-
readOnly={false}
|
|
135
|
-
/>
|
|
136
|
-
</CustomHomepageGrid>
|
|
137
|
-
</Content>
|
|
138
|
-
</Page>
|
|
139
|
-
);
|
|
140
|
-
```
|
|
141
|
-
|
|
142
|
-
Next, provide the [API token](https://support.pagerduty.com/docs/generating-api-keys#generating-a-general-access-rest-api-key) that the client will use to make requests to the [PagerDuty API](https://developer.pagerduty.com/docs/rest-api-v2/rest-api/).
|
|
143
|
-
|
|
144
|
-
Add the proxy configuration in `app-config.yaml`:
|
|
145
|
-
|
|
146
|
-
```yaml
|
|
147
|
-
proxy:
|
|
148
|
-
...
|
|
149
|
-
'/pagerduty':
|
|
150
|
-
target: https://api.pagerduty.com
|
|
151
|
-
headers:
|
|
152
|
-
Authorization: Token token=${PAGERDUTY_TOKEN}
|
|
153
|
-
```
|
|
154
|
-
|
|
155
|
-
Then, start the backend, passing the PagerDuty API token as an environment variable:
|
|
156
|
-
|
|
157
|
-
```bash
|
|
158
|
-
PAGERDUTY_TOKEN='<TOKEN>' yarn start
|
|
159
|
-
```
|
|
160
|
-
|
|
161
|
-
This will proxy the request by adding an `Authorization` header with the provided token.
|
|
162
|
-
|
|
163
|
-
#### Optional configuration
|
|
164
|
-
|
|
165
|
-
##### Annotating with Service ID
|
|
166
|
-
|
|
167
|
-
If you want to integrate a PagerDuty service with Backstage but don't want to use an integration key, you can also [annotate](https://backstage.io/docs/features/software-catalog/descriptor-format#annotations-optional) the appropriate entity with a PagerDuty Service ID instead
|
|
168
|
-
|
|
169
|
-
```yaml
|
|
170
|
-
annotations:
|
|
171
|
-
pagerduty.com/service-id: [SERVICE_ID]
|
|
172
|
-
```
|
|
173
|
-
|
|
174
|
-
This service ID can be found by navigating to a Service within PagerDuty and pulling the ID value out of the URL.
|
|
175
|
-
|
|
176
|
-
1. From the **Configuration** menu within PagerDuty, select **Services**.
|
|
177
|
-
2. Click the **name** of the service you want to represent for your Entity.
|
|
178
|
-
|
|
179
|
-
Your browser URL should now be located at `https://pagerduty.com/service-directory/[SERVICE_ID]`.
|
|
180
|
-
|
|
181
|
-
**Note:** *When annotating with `pagerduty.com/service-id`, the feature to Create Incidents is not currently supported*.
|
|
182
|
-
|
|
183
|
-
##### Custom Events URL
|
|
184
|
-
|
|
185
|
-
If you want to override the default URL used for events, you can add it to `app-config.yaml`:
|
|
186
|
-
|
|
187
|
-
```yaml
|
|
188
|
-
pagerDuty:
|
|
189
|
-
eventsBaseUrl: 'https://events.pagerduty.com/v2'
|
|
190
|
-
```
|
|
191
|
-
|
|
192
|
-
> **Note:** PagerDuty accounts based in Europe use a different url so you need to override it here if that is your case.
|
|
193
|
-
|
|
194
|
-
To suppress the rendering of the actionable incident-creation button, the `PagerDutyCard` can also be instantiated in `readOnly` mode:
|
|
195
|
-
|
|
196
|
-
```ts
|
|
197
|
-
<PagerDuty readOnly />
|
|
198
|
-
```
|
|
199
|
-
|
|
200
|
-
**WARNING**: In current implementation, the PagerDuty plugin requires the `/pagerduty` proxy endpoint be exposed by the Backstage backend as an unprotected endpoint, in effect enabling PagerDuty API access using the configured `PAGERDUTY_TOKEN` for any user or process with access to the `/pagerduty` Backstage backend endpoint. If you regard this as problematic, consider using the plugin in `readOnly` mode (`<PagerDutyCard readOnly />`) using the following proxy configuration:
|
|
201
|
-
|
|
202
|
-
```yaml
|
|
203
|
-
proxy:
|
|
204
|
-
'/pagerduty':
|
|
205
|
-
target: https://api.pagerduty.com
|
|
206
|
-
headers:
|
|
207
|
-
Authorization: Token token=${PAGERDUTY_TOKEN}
|
|
208
|
-
# prohibit the `/pagerduty` proxy endpoint from servicing non-GET requests
|
|
209
|
-
allowedMethods: ['GET']
|
|
210
|
-
```
|
|
211
|
-
|
|
212
|
-
## How to Uninstall
|
|
213
|
-
|
|
214
|
-
1. Remove any configuration added in Backstage yaml files, such as the proxy configuration in `app-config.yaml` and the integration key in an entity's annotations.
|
|
215
|
-
2. Remove the added code snippets from `EntityPage.tsx`
|
|
216
|
-
3. Remove the plugin package:
|
|
217
|
-
|
|
218
|
-
```bash
|
|
219
|
-
# From your Backstage root directory
|
|
220
|
-
yarn remove --cwd packages/app @pagerduty/backstage-plugin
|
|
221
|
-
```
|
|
222
|
-
|
|
223
|
-
4. [Delete the integration](https://support.pagerduty.com/docs/services-and-integrations#delete-an-integration-from-a-service) from the service in PagerDuty
|
|
224
|
-
|
|
225
|
-
## How to migrate from @backstage/plugin-pagerduty
|
|
226
|
-
|
|
227
|
-
If you are migrating from the Pagerduty plugin that was maintained by Spotify, the steps to migrate are pretty simple.
|
|
228
|
-
|
|
229
|
-
1. Remove the Backstage package from your project
|
|
230
|
-
|
|
231
|
-
```bash
|
|
232
|
-
# From your Backstage root directory
|
|
233
|
-
yarn remove --cwd packages/app @backstage/plugin-pagerduty
|
|
234
|
-
```
|
|
235
|
-
|
|
236
|
-
2. Install the new PagerDuty plugin for Backstage
|
|
237
|
-
|
|
238
|
-
```bash
|
|
239
|
-
# From your Backstage root directory
|
|
240
|
-
yarn add --cwd packages/app @pagerduty/backstage-plugin
|
|
241
|
-
```
|
|
242
|
-
|
|
243
|
-
3. Replace all occurrences of **@backstage/plugin-pagerduty** with **@pagerduty/backstage-plugin** in your components
|
|
244
|
-
|
|
245
|
-
4. Re-install dependencies and run Backstage locally to test that everything is working
|
|
31
|
+
### Configuration
|
|
246
32
|
|
|
247
|
-
|
|
248
|
-
# From your Backstage root directory
|
|
249
|
-
yarn install && yarn dev
|
|
250
|
-
```
|
|
33
|
+
To configure this frontend plugin follow the instructions on the `Getting Started` section of the project's documentation [here](https://pagerduty.github.io/backstage-plugin-docs/).
|
|
251
34
|
|
|
252
35
|
## Support
|
|
253
36
|
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@pagerduty/backstage-plugin",
|
|
3
3
|
"description": "A Backstage plugin that integrates towards PagerDuty",
|
|
4
|
-
"version": "0.7.
|
|
4
|
+
"version": "0.7.2-next.2",
|
|
5
5
|
"main": "dist/index.esm.js",
|
|
6
6
|
"types": "dist/index.d.ts",
|
|
7
7
|
"license": "Apache-2.0",
|
|
@@ -33,29 +33,30 @@
|
|
|
33
33
|
"clean": "backstage-cli package clean"
|
|
34
34
|
},
|
|
35
35
|
"dependencies": {
|
|
36
|
-
"@backstage/catalog-model": "^1.4.
|
|
37
|
-
"@backstage/core-components": "^0.13.
|
|
38
|
-
"@backstage/core-plugin-api": "^1.
|
|
39
|
-
"@backstage/errors": "^1.2.
|
|
40
|
-
"@backstage/plugin-catalog-react": "^1.
|
|
41
|
-
"@backstage/plugin-home-react": "^0.1.
|
|
42
|
-
"@backstage/theme": "^0.4.
|
|
36
|
+
"@backstage/catalog-model": "^1.4.3",
|
|
37
|
+
"@backstage/core-components": "^0.13.8",
|
|
38
|
+
"@backstage/core-plugin-api": "^1.8.0",
|
|
39
|
+
"@backstage/errors": "^1.2.3",
|
|
40
|
+
"@backstage/plugin-catalog-react": "^1.9.1",
|
|
41
|
+
"@backstage/plugin-home-react": "^0.1.5",
|
|
42
|
+
"@backstage/theme": "^0.4.4",
|
|
43
43
|
"@material-ui/core": "^4.12.2",
|
|
44
44
|
"@material-ui/icons": "^4.9.1",
|
|
45
45
|
"@material-ui/lab": "4.0.0-alpha.61",
|
|
46
|
-
"@types/react": "^16.13.1 || ^17.0.0",
|
|
47
46
|
"classnames": "^2.2.6",
|
|
48
47
|
"luxon": "^3.4.1",
|
|
49
|
-
"react": "^16.13.1 || ^17.0.0",
|
|
50
|
-
"react-dom": "^16.13.1 || ^17.0.0",
|
|
51
|
-
"react-router-dom": "6.0.0-beta.0 || ^6.3.0",
|
|
52
48
|
"react-use": "^17.2.4"
|
|
53
49
|
},
|
|
50
|
+
"peerDependencies": {
|
|
51
|
+
"react": "^16.13.1 || ^17.0.0 || ^18.0.0",
|
|
52
|
+
"react-dom": "^16.13.1 || ^17.0.0 || ^18.0.0",
|
|
53
|
+
"react-router-dom": "6.0.0-beta.0 || ^6.3.0"
|
|
54
|
+
},
|
|
54
55
|
"devDependencies": {
|
|
55
|
-
"@backstage/cli": "^0.
|
|
56
|
-
"@backstage/core-app-api": "^1.
|
|
57
|
-
"@backstage/dev-utils": "^1.0.
|
|
58
|
-
"@backstage/test-utils": "^1.4.
|
|
56
|
+
"@backstage/cli": "^0.24.0",
|
|
57
|
+
"@backstage/core-app-api": "^1.11.1",
|
|
58
|
+
"@backstage/dev-utils": "^1.0.24",
|
|
59
|
+
"@backstage/test-utils": "^1.4.5",
|
|
59
60
|
"@commitlint/cli": "^17.7.1",
|
|
60
61
|
"@commitlint/config-conventional": "^17.7.0",
|
|
61
62
|
"@testing-library/dom": "^8.0.0",
|
|
@@ -64,8 +65,12 @@
|
|
|
64
65
|
"@testing-library/user-event": "^14.0.0",
|
|
65
66
|
"@types/luxon": "^3.3.1",
|
|
66
67
|
"@types/node": "^16.11.26",
|
|
68
|
+
"@types/react": "^16.13.1 || ^17.0.0 || ^18.0.0",
|
|
67
69
|
"copyfiles": "^2.4.1",
|
|
68
70
|
"msw": "^1.2.4",
|
|
71
|
+
"react": "^16.13.1 || ^17.0.0 || ^18.0.0",
|
|
72
|
+
"react-dom": "^16.13.1 || ^17.0.0 || ^18.0.0",
|
|
73
|
+
"react-router-dom": "6.0.0-beta.0 || ^6.3.0",
|
|
69
74
|
"typescript": "^4.8.4"
|
|
70
75
|
},
|
|
71
76
|
"files": [
|