Opscraft
Platform engineering & Backstage · Lesson 3 of 5 · 4 min read

Backstage

What Backstage is

Backstage is an open-source framework for building developer portals, created at Spotify and now a CNCF project. Its core features:

  • Software catalogue: every service, website, library, API, data pipeline and resource, with its owner, lifecycle, dependencies and links (repository, dashboards, runbooks, on-call).
  • Software templates (the scaffolder): forms that run golden-path actions, such as creating a repo from a template, opening pull requests, registering in the catalogue.
  • TechDocs: documentation written in Markdown next to the code, built with MkDocs and shown in the portal.
  • Search across catalogue, docs and other sources.
  • Plugins: hundreds of them show Kubernetes workloads, Argo CD or Flux sync status, CI runs, PagerDuty on-call, costs, security findings and more on each service's page.
Enlarge diagramBACKSTAGEcatalogueservices, APIs,ownerstemplatesgolden pathsTechDocsdocs as codesearcheverythingpluginsKubernetes · Argo CD / Flux · CI runs · PagerDuty · cost · security findings
Figure 1. Backstage: one place to find any service, its owner, docs and live status, and to start new ones.
Swipe sideways to see all of it, or tap to open it full screen.

The catalogue

Entities are described in a catalog-info.yaml file in each repository, which Backstage discovers and ingests:

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: orders-api
  description: Creates and tracks customer orders
  annotations:
    github.com/project-slug: acme/orders-api
    backstage.io/kubernetes-id: orders-api
    argocd/app-name: orders-api-prod
    pagerduty.com/service-id: P1234AB
  tags: [java, payments]
spec:
  type: service
  lifecycle: production
  owner: group:team-orders
  system: checkout
  providesApis: [orders-api]
  dependsOn: [resource:orders-db]

Entity kinds include Component (a piece of software), API, Resource (a database, bucket or queue), System (a group of components forming a product), Domain, Group and User. Groups and users are usually synced from the identity provider.

Enlarge diagramDomain: commerceSystem: checkoutComponent: orders-apiservice, owner team-ordersAPI: orders-apiOpenAPI specResource: orders-dbRDS PostgreSQLComponent: cart-webwebsiteGroup: team-orderssynced from the identity provider
Figure 2. Catalogue entities and how they relate.
Swipe sideways to see all of it, or tap to open it full screen.

The catalogue is only valuable if it's accurate. Keep it close to the code (the YAML lives in each repo), generate it from templates for new services, validate it in CI, and use it: if incident tooling, cost reports and on-call routing all read ownership from the catalogue, teams have a reason to keep it right.

Running Backstage

Backstage is a framework, not a finished product: you create your own Backstage app (React front end, Node.js back end), add and configure plugins in code, and deploy and upgrade it yourself, typically on Kubernetes with a PostgreSQL database and single sign-on.

  • Budget real engineering time: a small team to maintain, upgrade and extend it.
  • Start with the catalogue and one or two high-value templates, not every plugin.
  • Hosted options (Roadie for managed Backstage) and commercial portals (Port, Cortex, OpsLevel, among others) trade flexibility for less maintenance.

Scorecards

Portals can grade services against standards with scorecards: has an owner, has a runbook, uses the current base image, has SLOs defined, passes security scans, no critical vulnerabilities older than 30 days. Scorecards make production readiness visible and turn platform migrations ("move to the new CI template") into a trackable campaign, as long as they're used to help teams rather than shame them.