The ultimate guide to running Spotify Backstage

Wondering how to go beyond “vanilla” Backstage and get the most out of this open-source developer portal? Learn about the additional features your team can build and customize in this guide.

December 30, 2021

Spotify Backstage is an open-source developer portal designed to increase productivity for software teams operating at scale. For organizations with growing microservices and development teams, it provides one centralized hub for service catalogs, templates, documentation, and internal tools.

As an open-source tool, Backstage requires a fair bit of engineering investment to implement for your organization. If you’re a newcomer to the platform, we recommend you start by reading our introduction to Spotify Backstage. However, if you’ve already gotten started with Backstage, we wrote this post to guide you through how to supercharge your Backstage instance with its top features.

Adding plugins to Backstage

Plugins, which are implemented using React components, are the basic unit of functionality in Backstage. You can think of Backstage as a single-page application composed of plugins with relevant features for each service in your catalog. There are a variety of plugins available on to choose from, or you can build your own! Here are some of the most popular ones:  


Datadog is a tool for application metrics, alerting, and logs. If your service teams are using Datadog, they likely interact with numerous metrics and dashboards. With the Datadog Backstage plugin, you can embed graphs with the most critical metrics directly into your service catalog. This way, those metrics can be easily accessed by members of your team and other relevant users across the org.


Kubernetes is a tool used by DevOps teams to orchestrate clusters of containerized apps. While service teams shouldn’t need to know or interact with the implementation details of Kubernetes, they benefit from direct visibility into production deployment information. With the K8s Backstage plugin, product engineers can check on the health of their services by viewing the state of deployments, pods, and ReplicaSets. The Kubernetes Backstage plugin communicates directly with the Kubernetes API, so it will work regardless of which cloud hosting provider you’re using.

Backstage Scaffolder

As orgs scale in size and start deploying tens, hundreds, or thousands of microservices, the process of instantiating new services becomes particularly cumbersome. In addition, if there aren’t well-defined standards and scaffolds for service creation, chaos can ensue.

This is why companies using microservice architecture have embraced tools that generate service templates. Service templates often include a basic scaffold for the application along with configurations for logging, metrics, CI/CD pipelines, testing, basic dependencies, and more. Backstage has direct support for writing service templates using the Scaffolder plugin. It also has built-in actions for publishing new services to a hosted git repository.

Cortex Scorecards

Scorecards are a popular feature in Cortex that provides quality tracking across services. With Scorecards, your organization can write customizable rules to assess service quality and reliability. You can even gamify the process by assigning points to top-performing services. Using the Cortex plugin, you can see Scorecards directly in your Backstage instance.

Custom plugins

If your team has developed internal tooling for managing your service, you can build a custom plugin and add it to Backstage. Each plugin can be thought of as a self-contained web app, capable of making API calls and rendering UI components.

You might start with a read-only plugin that pulls information about a service from an API and displays it on the service page. However, Backstage becomes more and more powerful as you add plug-ins with functionality like changing feature flags, triggering deployments, or kicking off maintenance jobs. Having these tasks consolidated in one place will improve their visibility and enhance your team’s productivity.

Organizing your Backstage instance

In addition to adding features to Backstage through plugins, you’ll want to spend some time organizing your catalog in a way that reflects the operating structure of your company. This includes importing org data, adding appropriate authentication, and grouping related content together.


In order to display which teams and individuals own each service, you’ll need to import org data into Backstage. Backstage offers convenient integrations with Github as well as any LDAP-compatible service to ingest this data. After import, Backstage will transform your org data into User and Group entities. A User is an individual at the company, and a Group is any collection of Users: a team, business unit, or special interest group. When using the Github or LDAP integrations, you won’t have to worry about manually updating Backstage with personnel changes — these changes will be synced automatically.


Once you’ve imported your users into Backstage, you’ll also want to configure authentication. Authentication can be used both to sign in to Backstage, as well as to authenticate the user to make other requests that may be required by plugins. Backstage has integrations with numerous authentication providers including Auth0, Github, Google, Okta, and OneLogin, among others.

Catalog Structure

As you add services to your catalog, you’ll want to think about how to organize them. We recommend organizing services by business systems rather than by teams. For instance, all services related to billing would be grouped together even if that spans many teams. Then you can use tags to indicate which team owns each service. This approach will help clarify your company’s microservice architecture and illuminate the chain of service dependencies for a particle business system. Furthermore, this approach is flexible in case there are re-orgs or a service switches team ownership.


The last part of organizing your Backstage instance is to implement search. Backstage Search is not a search engine. Instead, Backstage provides an interface to three search backends: Lunr, ElasticSearch, and Postgres. Configuring search for your Backstage instance will take some setup, but it is well worth the effort to make all the components of your service catalog discoverable. Note: Backstage Search is in Beta.

Get started supercharging your Backstage instance

We’ve highlighted a number of key Backstage features and given some guidance on how to organize your app in productive and secure ways. Backstage is under active development, so you’ll also want to keep your version up-to-date in order to take advantage of the latest and greatest tooling. We’d recommend checking for Backstage updates in an automated fashion, e.g. through GitOps. As you start developing on Backstage, you also might consider standing up a staging environment. A staging environment can help you test out new versions and plugins without interfering with production tools.

Backstage is an exciting and feature-rich tool in the open-source community. However, if after reading this post, you’re thinking that you don’t want to spend engineering resources to support Backstage development at your company, check out the product we’re building at Cortex. Cortex is a managed internal developer portal that provides service catalogs, scaffolds, scorecards, and other core features. Our focus is creating a seamless developer platform, so that your company can focus on delivering high-quality software.

What's driving urgency for IDPs?