RFC: PagerDuty Service Import/Mapping capabilities

[t1agob]

🔖 Need

The PagerDuty plugin provides a software project scaffolder custom action that enables the integration between Backstage and PagerDuty for new services but it is not possible to do the same for existing services.

I would like to have an easy way where I could see a list of Backstage entities and the PagerDuty services and easily map them together. The goal would be to have an easy way to map services without requiring the integration to be setup on each individual service.

This RFC is my proposal to solve issue (#80) but looking for different perspectives from the community.

🎉 Proposal

My proposal is to have a PagerDuty page that can be used used to import all PagerDuty Services to a list inside Backstage. From there you can use the UI to map PagerDuty services to existing Backstage entities.

The mappings will be stored on a database and will be checked for updates the next time a Backstage entity is loaded or when another import operation takes place. If the data is not in sync it will show on-screen. This might happen because the entity config was updated in source code. If this happens, the user will need to use the UI to select the new mapping or the old one.

All these mappings will only be persisted when the user clicks the "Save" button on the screen.

Example UI  👇

〽️ Alternatives

We have considered two alternatives instead of the UI-based approach mentioned above.
1. Providing a CLI tool to allow a fast mapping between PagerDuty and Backstage services
This would provide a similar approach to the one proposed above but instead of providing a UI-based interface to the user it would be done through CLI. For each mapping specified a PR would be created in the source code of that same service.

2. Create PRs to Backstage service code instead of storing the mapping on a database
This approach is similar to the one mentioned in the proposal section but instead of storing the mappings on a database and implement conflict management capabilities we would create PRs for every single mapping update.

The downside for these two approaches is that those PRs would require permissions to GitHub/GitLab/Azure DevOps and would still need to be approved and merged in every single service.

❌ Risks

We are introducing a database dependency that we didn't have before. This means that for service mapping capabilities the pagerduty.com/service-id is no longer the only option to configure the mapping between services in PagerDuty and Backstage.

Also, potentially in future changes, the database schema might change and therefore introduce the need for database migrations which adds up to the complexity of the plugin and its dependency management and versioning.

[brianphillips]

Personally, I prefer keeping the metadata in the catalog itself (whether in the source catalog-info.yaml files or as an enrichment step via a CatalogProcessor) as this makes it simpler for other tooling or plugins to make use of that integration key for their own purposes (they can get it directly from the catalog API vs. by integrating with some other plugin API endpoint).

[t1agob]

So, you would exclude the UI that allows users to map services and just map every single existing PagerDuty service into Backstage? Potentially merging with existing services if the names match?

Or would you still have the UI, allow users to map services manually, store the mapping into a database and when the processor runs, checks for existing mappings and updates the entities accordingly?

[brianphillips]

I think the UI sounds useful and I think that storing it in the DB and then merging that into the catalog data via a processor would be a straightforward way of providing that data to the rest of Backstage in a straightforward way.

[t1agob]

Perfect! We are aligned on that 🚀

[cal5barton]

I think my only concern is how this would work with those of us who have our catalog ingestion set to read-only. Would it be possible to automatically open PRs with the mappings?

[brianphillips]

I think my only concern is how this would work with those of us who have our catalog ingestion set to read-only. Would it be possible to automatically open PRs with the mappings?

It's definitely (technically) possible to submit PRs, assuming you have an integration configured in Backstage with your SCM provider that allows for creating PRs.

On the other hand, I don't think it's strictly necessary to take that route, at least in our environment. We also operate our Backstage instance that requires catalog entities to be ingested from our SCM provider (GitHub Enterprise Server, in our case) but even in the default configuration, the representation of an entity in Backstage is not 100% identical to what exists in SCM. If you go into the "Entity Inspector" and look at the YAML representation, you'll see that the core catalog processors add various annotations and other fields that aren't represented in the catalog-info.yaml file as configured in the SCM. In our case, we have additional catalog processors that take certain annotation values (which are configured by hand) and add various links or tags to the entity definition. The key being that all of that data is deterministic and can be recreated in an automatic fashion even if we wipe the database and start from scratch.

What's being proposed here is slightly different in that there would be additional state stored somewhere (in the Backstage DB) that is not strictly deterministic. That does put a little more burden on ensuring that the database never gets reset but I find that option preferable than trying to get hundreds of PRs merged across all of our different teams that own various components within Backstage.

[t1agob]

Hey folks!
We have released a new version for the plugin that introduces a first implementation of service mapping capabilities. Check the official docs for instructions on how to set it up 👉 https://pagerduty.github.io/backstage-plugin-docs/advanced/service-entity-mapping/

@cal5barton This release doesn't allow you to create PRs automatically in source code but should prevent you from using it even in read-only mode. I have created a new feature request (#116) to add the feature you requested at a later stage.