Skip to content

Backstage: a service catalog and golden paths

Platform Engineering · IDP
Not studied

Added 2026-10-29.

Problem

It's unclear who owns a service, where its repository, documentation and dashboards are. Every new service is assembled from scratch, each in its own way.

Solution

Backstage "is an open source framework for building developer portals. Powered by a centralized software catalog, Backstage restores order to your microservices and infrastructure". Out of the box it includes:

  • Software Catalog — "for managing all your software such as microservices, libraries, data pipelines, websites, and ML models", built from catalog-info.yaml files in the repositories;
  • Software Templates — "for quickly spinning up new projects and standardizing your tooling with your organization's best practices";
  • TechDocs — documentation with a "docs like code" approach, based on MkDocs.

Backstage is a framework, not a finished product: you build and maintain it as a separate application.

Example

catalog-info.yaml at the repository root:

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: devops-kb
  description: A personal DevOps knowledge base
  annotations:
    backstage.io/techdocs-ref: dir:.
spec:
  type: website
  lifecycle: production
  owner: andrew

The techdocs-ref annotation points to the directory with mkdocs.yml — the current site fits TechDocs almost unchanged.

When to use

When there are several services and teams, and "whose is this and how do I use it" comes up regularly. Overkill for one engineer and one VPS.

Source

How to apply it yourself

  1. Spin up the demo locally.
  2. Describe 2–3 of your services in catalog-info.yaml.
  3. Create one template for a new service.
  4. Record the maintenance effort; mark it "Studied" once there is a justified "adopt / don't adopt" decision.