diff --git a/.nojekyll b/.nojekyll new file mode 100644 index 0000000..e69de29 diff --git a/404.html b/404.html new file mode 100644 index 0000000..e06ebdb --- /dev/null +++ b/404.html @@ -0,0 +1,1099 @@ + + + +
+ + + + + + + + + + + + + + +The default URL used for REST API requests is https://api.pagerduty.com
. It is possible to override this URL through configuration. Add the following configuration to app-config.yaml
:
Note
+PagerDuty accounts based in Europe use a different URL so you need to override it here if that is your case.
+The default URL used for events is https://events.pagerduty.com/v2
. It is possible to override this URL through configuration. Add the following configuration to app-config.yaml
:
Note
+PagerDuty accounts based in Europe use a different URL so you need to override it here if that is your case.
+The correct url can be found in the Backstage integration page for your service on the PagerDuty console.
+ +The PagerDuty backend plugin provides a custom action that you can use in your Backstage Software Templates to create services in PagerDuty easily. This custom action not only creates the service, but also automatically configures a Backstage integration and adds its integration key to the Backstage Service configuration.
+By doing so, it enables and configures the PagerDuty Card provided by the frontend plugin directly on your service page, eliminating the need for manual configuration and enhancing the user experience.
+Note
+Version 0.6.0 of @pagerduty/backstage-plugin-backend
introduced support for the Backstage's new backend system which forced the extraction of the scaffolder actions to a separate package (@pagerduty/backstage-plugin-scaffolder-actions).
If you were already using the scaffolder actions before this, follow the migration guide here as you need to update the package used in the code.
+yarn add --cwd packages/backend @pagerduty/backstage-plugin-scaffolder-actions @pagerduty/backstage-plugin-common # (1)!
+
@pagerduty/backstage-plugin-scaffolder
and @pagerduty/backstage-plugin-common
packages to the packages/backend
folder because it is a backend module.You can add the custom action to the project in two different ways. Using the legacy backend system or the new backend system. Follow one of the approaches detailed below.
+Backstage Scaffolder capabilities can be extended with custom actions that support Software Templates. For that to happen you need to update packages/backend/src/plugins/scaffolder.ts
and add custom actions.
Now, the list of scaffolder actions cannot be appended so you need re-create it and append your custom action. Otherwise all actions will be replaced just with yours.
+// Add imports
+import { createBuiltinActions } from '@backstage/plugin-scaffolder-backend';
+import { ScmIntegrations } from '@backstage/integration';
+import { createPagerDutyServiceAction } from '@pagerduty/backstage-plugin-scaffolder-actions';
+
+export default async function createPlugin(
+ env: PluginEnvironment,
+): Promise<Router> {
+
+ ...
+
+ // Pull integrations
+ const integrations = ScmIntegrations.fromConfig(env.config);
+
+ // Rebuild built-in actions
+ const builtInActions = createBuiltinActions({
+ integrations,
+ catalogClient,
+ config: env.config,
+ reader: env.reader,
+ });
+
+ // Append PagerDuty custom action to the list
+ const actions = [
+ ...builtInActions,
+ createPagerDutyServiceAction()
+ ];
+
+ // Add new action list to the scaffolder
+ return await createRouter({
+ actions, // this is the only update needed on this list
+ logger: env.logger,
+ config: env.config,
+ database: env.database,
+ reader: env.reader,
+ catalogClient,
+ identity: env.identity,
+ permissions: env.permissions,
+ });
+}
+
This step registers the custom action with the Scaffolder and allows it to be used in the Software template which you will configure on next step.
+Backstage's new backend system simplifies the configuration of backend plugins and requires less code to setup plugins. To add the PagerDuty scaffolder actions to your Backstage application add the following in packages/backend/src/index.ts
.
Software Templates can be simple or complex depending on the practices you are trying to standardize across your teams. Here, we provide a simple example of a template that requests basic information for a Backstage service and augments that with information relevant for creating the service in PagerDuty.
+Note
+We assume you have an examples/template/content
folder which is automatically create when you use npx @backstage/create-app
to create your Backstage project.
In your examples/template/content
folder you should create catalog-info.yaml
file if you don't have one already. Update its content to something like this:
apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+ name: ${{ values.name | dump }}
+ annotations:
+ pagerduty.com/integration-key: ${{ values.integrationKey | dump }}
+ pagerduty.com/service-id: ${{ values.serviceId | dump }}
+spec:
+ type: website
+ lifecycle: experimental
+ owner: guests
+
In the software template we will either replace the values for the integration-key
, service-id
and name
or completely remove the parameters from the configuration.
Note
+You don't need to use this exact template but to automate the configuration for the PagerDuty Card you need to have at least the integration-key
or the service-id
parameters.
Now that we have defined the contents of the new project we will be creating through a Software Template, we need to create the template itself.
+Software templates are composed of input parameters, steps and outputs. In the following template we provide the user with two pages:
+Once all the information is provided by the user we will:
+catalog-info.yaml
file and replace the variables with the values generated by the previous stepNote
+For the following template to work, you need to configure the apiToken
in app-config.yaml
file. If you haven't done so, follow the steps in Configure Backend plugin API credentials
Note: If you don't setup this property in your configuration, the backend plugin will fail to start.
+Note
+The UI component that allows users to select the Escalation Policy when creating a new service in PagerDuty depends on an open source component. For the template to work properly please install it before.
+ +Once it is installed, go to /packages/app/src/App.tsx
and find <ScaffolderPage />
. Add the UI component to ScaffolderFieldExtensions
. It should look like this when you finish.
import { ScaffolderFieldExtensions } from '@backstage/plugin-scaffolder-react';
+import { SelectFieldFromApiExtension } from '@roadiehq/plugin-scaffolder-frontend-module-http-request-field';
+
+...
+
+<Route path="/create" element={<ScaffolderPage />}>
+ <ScaffolderFieldExtensions>
+ <SelectFieldFromApiExtension />
+ </ScaffolderFieldExtensions>
+</Route>
+
Once all requirements are in-place, create a template.yaml
file under examples/template
and copy the following code in there.
apiVersion: scaffolder.backstage.io/v1beta3
+kind: Template
+metadata:
+ name: create-pagerduty-service
+ title: Create PagerDuty Service
+ description: Creates service in PagerDuty
+spec:
+ owner: pagerduty
+ type: service
+
+ parameters:
+ - title: PagerDuty Service
+ required:
+ - service_name
+ - description
+ - escalation_policy_id
+ properties:
+ service_name:
+ title: Service Name
+ type: string
+ description: The name of the service
+ description:
+ title: Description
+ type: string
+ description: The description of the service
+ escalation_policy_id:
+ title: Escalation Policy ID
+ type: string
+ description: The ID of the escalation policy to associate with the service
+ ui:field: SelectFieldFromApi #(1)!
+ ui:options: #(2)!
+ title: PagerDuty Escalation Policy
+ description: Select an escalation policy from PagerDuty
+ path: 'pagerduty/escalation_policies' #(3)!
+ labelSelector: 'label'
+ valueSelector: 'value'
+ placeholder: '---'
+ alert_grouping: #(4)!
+ title: Alert Grouping
+ type: string
+ description: Reduce noise by grouping similar alerts - Defaults to 'None'.
+ enum:
+ - 'time'
+ - 'intelligent'
+ - 'content_based'
+ enumNames:
+ - 'Time-based grouping'
+ - 'Intelligent grouping'
+ - 'Content-based grouping'
+
+ - title: Choose a location
+ required:
+ - repoUrl
+ properties:
+ repoUrl:
+ title: Repository Location
+ type: string
+ ui:field: RepoUrlPicker
+ ui:options:
+ allowedHosts:
+ - github.com
+
+ steps:
+ - id: pagerdutyService
+ name: Create PagerDuty Service
+ action: pagerduty:service:create
+ input:
+ name: ${{ parameters.service_name }}
+ description: ${{ parameters.description }}
+ escalationPolicyId: ${{ parameters.escalation_policy_id }}
+ alertGrouping: ${{ parameters.alert_grouping }} #(5)!
+
+ - id: fetch-base
+ name: Fetch Base
+ action: fetch:template
+ input:
+ url: ./content
+ templateFileExtension: '.yaml'
+ values:
+ name: ${{ parameters.service_name }}
+ serviceId: ${{ steps['pagerdutyService'].output.serviceId }}
+ integrationKey: ${{ steps['pagerdutyService'].output.integrationKey }}
+
+ - id: publish
+ name: Publish
+ action: publish:github
+ input:
+ allowedHosts: ['github.com']
+ description: This is ${{ parameters.name }}
+ repoUrl: ${{ parameters.repoUrl }}
+
+ - id: register
+ name: Register
+ action: catalog:register
+ input:
+ repoContentsUrl: ${{ steps['publish'].output.repoContentsUrl }}
+ catalogInfoPath: '/catalog-info'
+
+ output:
+ links:
+ - title: Open in PagerDuty
+ url: ${{ steps['pagerdutyService'].output.serviceUrl }}
+ text:
+ - title: Integration Key
+ text: ${{ steps['pagerdutyService'].output.integrationKey }}
+
@roadiehq
that queries data from a local APIThis is an easy mechanism for onboarding new services in an automated way, ensuring that Backstage and PagerDuty services can be provisioned with one step and in a self-service way.
+ + + + + + + + + + + + + + + + + +The PagerDuty plugin allows users to create incidents directly from Backstage. This feature is enabled by default but you can choose to disable it.
+ +To suppress the rendering of the actionable incident creation button, the PagerDutyCard
can be instantiated in readOnly
mode as shown below.
This will hide the button for all users and prevent incidents from being created from Backstage.
+ + + + + + + + + + + + + + + + + + +The PagerDuty plugin allows users to view the recent changes made to components integrated with their PagerDuty service. This feature is enabled by default but you can choose to disable it.
+ +Note
+In order to ingest change events in PagerDuty you need to have an AIOps license. If you don't have one, or you are missing the necessary permissions, you will see the following error.
+ +This is one of the reasons why users might want to disable this capability. PagerDuty has decided not to hide the tab automatically due to its relevance in the incident operations process.
+To suppress the rendering of the change events tab, the PagerDutyCard
can be instantiated with a disableChangeEvents
option as shown below.
This will hide the change events tab for all users and prevent recent changes from being visible in Backstage.
+ + + + + + + + + + + + + + + + + + +The PagerDuty plugin allows users to view relevant metrics for the service. This feature is enabled by default but you can choose to completely hide it.
+Note
+This capability is only available for the PagerDutySmallCard
at this point in time.
To suppress the rendering of the insights section, the PagerDutySmallCard
can be instantiated with a disableInsights
option as shown below.
This will hide the insights tab for Backstage users.
+ + + + + + + + + + + + + + + + + + +The PagerDuty plugin allows users to view who is currently on-call for the escalation policy assigned to the service. This feature is enabled by default but you can choose to completely hide it.
+ +To suppress the rendering of the on-call section, the PagerDutyCard
can be instantiated with a disableOnCall
option as shown below.
This will hide the on-call tab for Backstage users.
+ + + + + + + + + + + + + + + + + + + +The most common use case for the plugin is to have an instance of the plugin in each service. Still, you might want to have multiple instances of the plugin in your homepage to provide visibility on multiple services at the same time.
+Warning
+The PagerDutyHomepageCard
has not yet been updated to match the new UI of the PagerDutyCard
released on version 0.10.0
of the frontend plugin.
If that is your case you might want to leverage the PagerDutyHomepageCard
component like so.
...
+export const homePage = (
+ <Page themeId="home">
+ ...
+ <Content>
+ <CustomHomepageGrid config={defaultConfig}>
+ ...
+ <PagerDutyHomepageCard
+ name="My Service"
+ serviceId="<service-id>"
+ integrationKey="<integration-key>"
+ readOnly={false}
+ />
+ </CustomHomepageGrid>
+ </Content>
+ </Page>
+);
+
This component requires you to specify the service-id
and integration-key
properties which allows for added flexibility.
Note
+We are aware that this scenario is not ideal as the homepage will be full of different components and will be difficult to navigate on and for that reason we are working on a component that provides an aggregated view on multiple services.
+Until we release that capability this is the best option if you want to provide visibility on multiple services on the same page.
+Users of PagerDuty plugin for Backstage are typically customers of PagerDuty that have started to use Backstage as their Internal Developer Portal. This means they start from an existing base of PagerDuty services that they need to manually configure to have them show up in Backstage.
+This can of course be automated through the use of PagerDuty's APIs but it's still something that requires human effort and for some teams it is difficult to justify the investment.
+For that reason we create a PagerDutyPage
component that is intended to be the single place for advanced configurations related to this plugin.
++At this point in time the
+PagerDutyPage
only allows Admins to map existing PagerDuty services to Backstage entities. Other features will be released in the future.
In order to set this up in your Backstage instance you should install the necessary packages first by running the following command. This command will install the entity processor module that we will configure later on.
+ +Note
+The following instructions assume that you already installed the frontend and backend plugin as described in the Getting Started page.
+The Entity Processor module is one of the key components of this capability as it allows for entity mapping configurations that were persisted into the Backstage database to be applied to each Backstage entity configuration.
+You can enable the entity processor in your Backstage instance by injecting the dependency in the backend system in packages/backend/index.ts
.
import { createBackend } from '@backstage/backend-defaults';
+
+ const backend = createBackend();
+
+ ...
+
+ backend.add(import('@pagerduty/backstage-plugin-entity-processor')); // <-- This is the line you want to add
+
+ backend.start();
+
And that is it for the entity processor module. This module will process all Backstage entities and if there are any changes persisted to the database they will be applied automatically.
+Now that we have taken care of the backend configurations we need to expose the mapping features to the Backstage Admins. You do this in two steps.
+PagerDutyPage
componentIn packages/app/src/App.tsx
import the PagerDutyPage
component from @pagerduty/backstage-plugin
by using the following command.
Add a new route to your routes list.
+ const routes = (
+ <FlatRoutes>
+ ...
+ <Route path="/pagerduty" element={<PagerDutyPage />} />
+ </FlatRoutes>
+ );
+
In packages/app/src/components/Root/Root.tsx
import the PagerDutyIcon
component from @pagerduty/backstage-plugin
by using the following command.
Add the menu option to navigate to the new /pagerduty route.
+ export const Root = ({ children }: PropsWithChildren<{}>) => (
+ <SidebarPage>
+ <Sidebar>
+ ...
+ <SidebarGroup label="Menu" icon={<MenuIcon />}>
+ ...
+ <SidebarItem icon={PagerDutyIcon} to="pagerduty" text="PagerDuty" />
+ ...
+ </SidebarGroup>
+ </Sidebar>
+ {children}
+ </SidebarPage>
+ );
+
Now, Backstage Admins will have the option to configure the mapping between PagerDuty services and Backstage entities using a UI.
+Once you navigate to the new /pagerduty
route will see a page similar to the one below. On the table you will see a list of all your PagerDuty services, it's current mapping and the mapping status.
To define the mapping between existing PagerDuty services and Backstage entities you need to select the edit option on the right. Once you do so, a new modal screen will pop-up. Here, you can choose from a list of available Backstage entities that you want to map to the PagerDuty service.
+Warning
+Currently we only support 1:1 mapping between PagerDuty services and Backstage entities due to a limitation on the PagerDutyCard
that only supports one service at a time. There is work in progress to overcome this limitation.
Once you select a new mapping, Backstage Entity Processor will be instructed to run and update the Backstage entity configuration. This is a best-effort action and the configuration update might not be immediate.
+Mappings defined on this page are not persisted to source code but instead kept in Backstage database. For this reason, we allow you to check the mapping status for each PagerDuty service. The status might take one of the following values:
+With this information the user can chose whether to manually persist the override to the source code and therefore ensure the configuration is in sync.
+Note
+We are evaluating an option to automatically create a PR in the source repo for the Backstage entity to ease the process of ensuring that configurations are in sync. Still, this feature is not available yet.
+And there you go. This is all you need to do to map your existing PagerDuty services to Backstage entities in an easier manner.
+ + + + + + + + + + + + + + + + + +