Backstage: Spotify’s Developer Portal

javi
Pantalla de monitor con paneles de control de aplicaciones

Backstage, open-sourced by Spotify in 2020, is the most-used foundation for building Internal Developer Platforms (IDPs). In 2023 it has consolidated as the reference — adopted by companies like Spotify, American Airlines, Netflix, Roku, and hundreds more. It’s not a closed product: it’s an extensible platform each organisation adapts. We cover how it works, what you get out of the box, and the adoption costs rarely mentioned in talks.

What It Really Is

Backstage is a web application (Node.js + React) acting as a single portal for everything a developer needs at work:

  • Service catalog: centralised inventory of what exists, who maintains it, its dependencies.
  • Plugins: each additional function (CI/CD status, Kubernetes, monitoring, docs, cloud costs) comes as a pluggable plugin.
  • Scaffolder: new-component generator from templates.
  • TechDocs: documentation as code, rendered inside the portal.
  • Search: federated search over all of the above.

The vision: a single place where the developer finds what exists, how to create new things, where the docs are, what’s happening with their services.

Software Catalog: The Heart

Each thing in Backstage is a catalog entity, described by a simple YAML:

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: orders-api
  description: Service that manages purchase orders
spec:
  type: service
  lifecycle: production
  owner: team-orders
  system: ecommerce

Main entity types: Component (services, libraries, websites), API, Resource (DBs, queues), System (groupings), Group (teams), User, Domain (functional areas).

Relationships are inferred from YAML: “this component belongs to system X, its API is consumed by Y, it’s in domain Z”. Backstage builds a navigable network of the whole architecture.

The catalog is fed by:

  • Locations (URLs of YAMLs). Can live in each service’s repo or centralised.
  • Providers that automatically discover entities (from a Kubernetes cluster, GitHub orgs, etc.).
  • Manually via the web interface.

Plugins: Where the Ecosystem Lives

Backstage is only useful with plugins. Some essentials:

  • GitHub / GitLab: see the repo, PRs, contributors directly in the portal.
  • CI/CD: build, deploy, run status (Tekton, ArgoCD, Jenkins, GitHub Actions).
  • Kubernetes: see pods, deployments, events for the current component.
  • TechDocs: markdown documentation inside the portal.
  • PagerDuty / Opsgenie: current oncall for each service.
  • Datadog / Grafana / NewRelic: embedded component dashboards.
  • Sentry / Rollbar: recent errors.
  • Cost Insights: cloud cost per service.

There are 100+ official and community plugins. And building your own is a React exercise + a couple of config files.

The Scaffolder: Golden Paths in Action

The scaffolder is where Backstage turns the “platform engineering” promise into reality. You define templates that generate:

  • New GitHub repository with standard structure.
  • Configured CI pipeline.
  • Kubernetes manifests with resource limits and health checks.
  • Pre-created Grafana dashboard.
  • Basic alerts.
  • Catalog entry pointing to the new component.

All from a web wizard where the developer fills in few fields (name, team, type). What would take hours or days manually, takes a minute.

Implementing it requires investment: each template is code (YAML + shell + Backstage actions), and maintaining it as internal conventions change is ongoing work.

TechDocs: Docs as Code

TechDocs renders markdown from the service’s own repo inside the portal. The idea: documentation lives with the code, updates in the same PRs, and is seen with good UX in a centralised place.

Internally it uses MkDocs as the rendering engine. Integration is simple: add a mkdocs.yml and docs/ folder to the repo, reflect in catalog-info.yaml, and it appears in Backstage.

It’s one of the most adopted features because it solves a real problem: documentation scattered across Confluence, wikis, READMEs, and PDFs.

The Real Cost of Adopting Backstage

Talks sell Backstage as “install and ready”. The reality of seriously implementing it:

  • Dedicated team. Adopting it well requires 1-3 full-time engineers for months for configuration, plugins, and migration.
  • Continuous investment. Plugins evolve, integrations change, templates need maintenance. It’s not a “project” — it’s an internal product.
  • React/Node.js learning curve. If your team is backend-heavy, adopting the Backstage frontend is a new skill.
  • Data in good state. If your current inventory is an outdated Excel, Backstage won’t fix it — only expose it.
  • Cultural adoption. Developers must go to the portal, maintain their catalog-info, write TechDocs. Without organisational push, it’s underused.

For organisations with fewer than 30-50 developers, the investment rarely pays off. For larger ones, ROI can be substantial — but requires real commitment.

Alternatives and Managed Options

Backstage isn’t the only option:

  • Port: managed SaaS with catalog and portal, less flexibility but zero operations.
  • Cortex: similar, focus on service catalog and scorecards.
  • Roadie and Spotify Portal for Backstage: managed Backstage version by external companies.
  • Custom build: for organisations with very specific stack, sometimes a custom dashboard works better.

Conclusion

Backstage is the default choice if your organisation has the scale and commitment to build a serious IDP. Its flexibility is its strength and its demand: it forces you to make decisions other more opinionated tools resolve for you. If you get the investment and organisational backing right, the result is valuable. If you treat it as “install Backstage on Fridays”, it’ll end up half-done.

Follow us on jacar.es for more on platform engineering, IDP, and developer experience.

Entradas relacionadas