Spotify Backstage - everything you need to know

What is Spotify Backstage?

Spotify Backstage, better known by the industry simply as Backstage, is the first and most popular internal developer portal. Portals are a key category within the emerging space of platform engineering. And according to Gartner’s definition, they’re one of the main interfaces through which developers can access the capabilities of an Internal Developer Platform i.e. the platform layer of an enterprise engineering organization.

Backstage was built internally at Spotify with its core functionality intended as a software and service catalog. It was later open-sourced in March 2020 and donated to the Cloud Native Computing Foundation (CNCF). Since then it has quickly grown to become one of the most sought-after solutions for platform engineering initiatives and in 2021, Thoughtworks and Spotify made their collaboration on Backstage public, to make Backstage more enterprise-friendly and implement it at scale.

While Backstage is still by far the most popular internal developer portal whether in terms of search traffic, forks, or mentions, the challenges surrounding adoption and rolling it out in an enterprise setting have been gaining industry momentum. More and more teams realize that implementation can often become a 6 to 12-month slog with varying degrees of success. And it’s these factors, like its limited enterprise friendliness and complex implementation, that have given rise to a whole new set of commercial alternatives.

In this guide, we’ll walk through the key Backstage features and benefits, challenges and limitations, and what this all means for your platform engineering initiative.

Why did Spotify develop Backstage?

According to Spotify, Backstage was developed internally to improve both developer onboarding and developer experience (DevEx). The internal platform team at Spotify wanted to enable developer self-service by providing their engineers with clear paved roads and golden paths. They also needed a clear overview of service ownership to improve auditability and enable reusability.

Spotify explained that before introducing Backstage, developers spent too much time searching for information on how to do things the right way, instead of actually developing code. Backstage was built to remove this cognitive load and extra pressure on developers to figure out things on their own, so they could focus on shipping core product functionality.

What are the core features of Backstage?

Backstage’s architecture revolves around the concept of plugins, in order to make it extensible and versatile for different use cases. The below core features mirror the respective plugins:

Software or service catalog

This was the main focus of the Backstage team when they first developed it. The software catalog is a centralized system that tracks all necessary metadata (e.g. service ownership) for the different software components of an ecosystem, such as services, websites, libraries, pipelines, etc. This is done by using metadata YAML files stored together with the application code, which are then harvested and visualized through Backstage.

Templates

The templates plugin lets platform teams predefine service templates and blueprints that developers can easily access and use to create new services, which are already following the latest standards and best practices. Once services have been created out of templates, they’re registered in the software catalog and include all related metadata.

TechDocs

This is a docs-as-code plugin built into Backstage to enable auto-documentation, improve the overall auditability of a setup, and support developers with getting-started guides.

Search

The search plugin is customizable and enables engineering organizations to connect their own search engine, e.g. ElasticSearch, Lunr, Postgres, etc. to search both Backstage Software Catalog and TechDocs.

Kubernetes (K8s) (plugin)

The Kubernetes plugin is designed to let service owners check on the health of their K8s services. The frontend plugin provides an overview of errors identified, alongside deployments, pods, containers, etc.

Main Backstage use cases 

Accelerating developer onboarding: By leveraging a portal, new team members can swiftly familiarize themselves with your platform setup and the underlying toolchain. This centralized interface simplifies the intricacies of your infrastructure, enabling quick initiation.

It's important to note that the portal doesn't entirely shield developers from configurations or restrict access. In platform engineering, adopting a platform-as-a-product approach involves continuous refinement of both the platform and portal based on developer feedback. This iterative process is essential for creating streamlined pathways that reduce complexity while retaining necessary context for developers.

Unified developer experience (DevEx): Developer portals serve as a key mechanism for engineering organizations to deliver a consistently high-quality DevEx. This holds true for every engineer within the company, regardless of their team or familiarity with specific tools. Netflix's platform team shared valuable insights on this aspect during their presentation at PlatformCon23.

Inner-sourcing: The service catalog feature makes it easy to discover existing services developed or used by other teams. While this prevents redundant efforts, it's more about fostering broader alignment than achieving complete reusability.

Scaffolding through templates: Developers can expedite their project kick-off by using service templates available in the portal, ensuring adherence to the latest security standards and organizational configuration blueprints.

Metric tracking: Despite their nomenclature, internal developer portals often serve management purposes as well. Dashboards with automatically monitored metrics on developer productivity, team performance, and ownership metadata in service catalogs offer valuable insights for making informed decisions.

Known issues with Backstage

There are a few important issues that are being increasingly recognized and discussed by the community when it comes to Backstage implementation.

One key thing to understand here is that Backstage was developed to meet the specific needs of the Spotify engineering org. As such, it’s not designed for an easy, universal, plug-and-play type of implementation.

It’s now been reported by many teams of all sizes, especially enterprises, that Backstage is hard to set up and takes much longer than often forecast (up to 12+ months for larger setups). It’s also hard to configure and difficult to maintain, particularly after the initial excitement from management wanes and as the rollout moves slowly.

So while Spotify reports a voluntary 99% portal adoption rate, other engineering organizations that tried to implement it report an average adoption rate stuck at around 10%. 

Backstage alternatives

Because of the complexity of installing and rolling out Backstage, a few closed-source, commercial alternatives have gained market share in the last two years:

Cortex: This developer portal provides a catalog, scorecards, a scaffolder, and numerous integrations. Learn about the collaborative synergy between Cortex and the Humanitec Platform Orchestrator.

Humanitec Portal: In addition to their core Platform Orchestrator and open-source workload specification (Score), Humanitec has introduced its own Portal. This makes it a comprehensive and ideal one-stop-shop solution for enterprise platform engineering.

Getport.io: Getport.io, a commercial portal vendor, works seamlessly with Humanitec. Its primary functionalities encompass a catalog, scorecards, automation, and dashboards.

Configure 8: Another commercial portal vendor that provides a catalog, scorecards, and automation, with forthcoming additions of cost management features.

OpsLevel: The primary offering revolves around a catalog featuring AI support for metadata creation and Docs-as-code capabilities.

Rely: Rely provides a catalog, scorecards, dashboards, and SLO tracking as part of its offerings.

Compass by Atlassian: Officially launched in October 2023, Compass natively integrates with JIRA and is free of charge to all Jira users. This makes it extremely easy to go from grooming to production, in one flow. Compass has an integration with the Humanitec Platform Orchestrator.

Note that all internal developer portals can be used as interfaces for an Internal Developer Platform (IDP) built around Humanitec Platform Orchestrator and Score.

You can choose any portal you want to use or use Humanitec’s own Portal offering.

Maximize IDP value with a portal 

Portals contribute great value to engineering organizations by facilitating service discoverability and templating, enhancing DevEx and onboarding processes, and offering transparency in key performance metrics.

However, it's crucial to bear in mind that portals serve as interfaces to your platform rather than being the platform itself. Internal developer portals don't address the fundamental challenges of configuration and infrastructure orchestration, which only an enterprise-grade IDP can do. If you’re keen to learn more about delivering an IDP that’s truly enterprise-ready, we recommend checking out our reference architectures developed with the Humanitec Platform Orchestrator.