Backstage

platformengineering/backstage cncf

Tldr

Backstage is an open-source developer portal platform built by Spotify and donated to the Cloud Native Computing Foundation (CNCF). It centralizes tooling, services, documentation, and infrastructure into a single, unified developer experience.
It acts as an interactive front-end on top of complex backend tools, allowing teams to monitor and control infrastructure, application catalogs, and CI/CD workflows without relying strictly on terminal commands

1. What Is Backstage?

¹Backstage is a developer portal framework that solves the “tooling sprawl” problem in large engineering organizations. Instead of engineers jumping between dozens of dashboards, CI/CD tools, cloud consoles, and wikis, Backstage brings everything into one place.

Created by: Spotify (2020, open-sourced)
Adopted by: CNCF (Incubating → Graduated project)
Language: TypeScript / React (frontend), Node.js (backend)
License: Apache 2.0

Key Concepts

Source Code, Not a Product: Unlike typical software, Backstage provides no official out-of-the-box Docker images or Helm charts to deploy directly. It is a codebase you download, modify locally, and customize to your business needs.
Plugins: Its functionality is highly extensible through a modular ecosystem. You can install pre-built community plugins or write your own.
Components: These represent logical entities in your system—such as front-end websites, backend APIs, databases, or managed Kubernetes clusters.
Templates: These define customized, dynamic UI wizard forms that let users generate infrastructure configurations easily without having to write code from scratch

Managing Backstage requires significant TypeScript and Node.js expertise, and configuring everything can feel exceptionally verbose and redundant compared to standard Kubernetes setups.

Demo

Getting Started with Backstage: From Zero to Operational Dev Portal

2. Core Problem Backstage Solves

Problem	Backstage Solution
Engineers can’t find services or their owners	Software Catalog
Documentation is scattered everywhere	TechDocs
Creating new services is slow & inconsistent	Software Templates (Scaffolder)
Too many dashboards to check	Unified Plugin Interface
Infrastructure visibility is siloed	Kubernetes, CI/CD Plugins

3. Architecture Overview

┌─────────────────────────────────────────────────────────┐
│                      Backstage App                      │
│                                                         │
│  ┌──────────────┐  ┌────────────────┐  ┌────────────┐   │
│  │   Frontend   │  │    Plugins     │  │  Backend   │   │
│  │  (React SPA) │  │  (UI + APIs)   │  │ (Node.js)  │   │
│  └──────┬───────┘  └───────┬────────┘  └─────┬──────┘   │
│         │                  │                  │         │
│         └──────────────────┴──────────────────┘         │
│                            │                            │
│              ┌─────────────┴──────────────┐             │
│              │      Backstage Core APIs   │             │
│              │  Catalog / Auth / Search / │             │
│              │  Config / Identity / Proxy │             │
│              └────────────────────────────┘             │
└─────────────────────────────────────────────────────────┘

Backstage has three tiers:

Core — Foundational APIs (Catalog API, Config API, Auth API, etc.)
App — Your organization’s customized Backstage instance
Plugins — Feature modules (first-party + third-party + custom)

4. The Software Catalog

The Software Catalog is the heart of Backstage. It is a registry of all your organization’s software and infrastructure.

Entity Kinds

Kind	Description	Example
`Component`	A deployable unit of software	Microservice, website, library
`API`	An interface exposed by a component	REST, gRPC, GraphQL, AsyncAPI
`Resource`	Infrastructure a component depends on	S3 bucket, PostgreSQL DB
`System`	A collection of related components/APIs	Payment System
`Domain`	A business domain grouping systems	Checkout Domain
`Group`	An organizational team or business unit	Backend Team
`User`	An individual developer	john.doe
`Location`	A pointer to other catalog YAML files	GitHub org file
`Template`	A Software Template for scaffolding	Node.js Service Template

The `catalog-info.yaml` File

Every entity is described by a YAML descriptor file committed to the code repository:

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: payment-service
  description: Handles all payment transactions
  tags:
    - payments
    - node
  annotations:
    github.com/project-slug: myorg/payment-service
    backstage.io/techdocs-ref: dir:.
spec:
  type: service
  lifecycle: production
  owner: payments-team
  system: checkout-system
  providesApis:
    - payment-api
  dependsOn:
    - resource:postgres-payments-db

Key Metadata Fields

apiVersion — always backstage.io/v1alpha1 or v1beta1
kind — entity type (Component, API, System, etc.)
metadata.name — unique identifier
metadata.annotations — integration hooks (GitHub, PagerDuty, Sentry, etc.)
spec.owner — team or user responsible
spec.lifecycle — experimental, production, deprecated
spec.type — component type: service, website, library, tool

How Catalog Ingestion Works

Repository (catalog-info.yaml)
        │
        ▼
  Catalog Processor
        │
  ┌─────▼──────┐
  │  Validate  │
  │  Resolve   │
  │  Relations │
  └─────┬──────┘
        │
  ┌─────▼──────────────────┐
  │   Catalog Database     │
  │ (SQLite / PostgreSQL)  │
  └────────────────────────┘
        │
  Backstage UI + API

5. Software Templates (Scaffolder)

The Scaffolder lets teams create new services, libraries, or resources using pre-defined templates — with a form-driven wizard UI.

Template Structure

apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: nodejs-service-template
  title: Node.js Microservice
  description: Creates a production-ready Node.js service
  tags:
    - node
    - recommended
spec:
  owner: platform-team
  type: service
 
  parameters:
    - title: Service Details
      required: [name, description]
      properties:
        name:
          title: Service Name
          type: string
          pattern: '^[a-z0-9-]+$'
        description:
          title: Description
          type: string
        owner:
          title: Owner
          type: string
          ui:field: OwnerPicker
 
  steps:
    - id: fetch
      name: Fetch Template
      action: fetch:template
      input:
        url: ./skeleton
        values:
          name: ${{ parameters.name }}
          description: ${{ parameters.description }}
 
    - id: publish
      name: Publish to GitHub
      action: publish:github
      input:
        allowedHosts: ['github.com']
        repoUrl: github.com?owner=myorg&repo=${{ parameters.name }}
 
    - id: register
      name: Register in Catalog
      action: catalog:register
      input:
        repoContentsUrl: ${{ steps.publish.output.repoContentsUrl }}
        catalogInfoPath: /catalog-info.yaml
 
  output:
    links:
      - title: Repository
        url: ${{ steps.publish.output.remoteUrl }}
      - title: Open in Catalog
        entityRef: ${{ steps.register.output.entityRef }}

Built-in Scaffolder Actions

Action	Description
`fetch:template`	Render a Cookiecutter/Nunjucks template
`fetch:plain`	Copy files as-is
`publish:github`	Create a GitHub repository
`publish:gitlab`	Create a GitLab project
`publish:bitbucket`	Create a Bitbucket repo
`catalog:register`	Register new entity in catalog
`catalog:write`	Write catalog YAML to workspace
`github:actions:dispatch`	Trigger a GitHub Actions workflow

6. TechDocs

TechDocs is Backstage’s docs-as-code solution. It renders Markdown documentation (written with MkDocs) directly inside Backstage.

How It Works

/docs/
  index.md
  architecture.md
  api-reference.md
mkdocs.yml
catalog-info.yaml  ← links to docs

`mkdocs.yml` Example

site_name: Payment Service
docs_dir: docs
nav:
  - Home: index.md
  - Architecture: architecture.md
  - API Reference: api-reference.md
plugins:
  - techdocs-core

Annotation in `catalog-info.yaml`

annotations:
  backstage.io/techdocs-ref: dir:.

TechDocs Build Modes

Mode	Description
`local`	Build docs on-the-fly (dev/testing)
`external`	Pre-built docs stored in object storage (S3, GCS, Azure Blob) — recommended for production

7. Plugins

Plugins are the extension mechanism of Backstage. Everything in Backstage is a plugin — even the Catalog and Scaffolder.

Plugin Types

Type	Description
Frontend Plugin	React-based UI tab/page added to Backstage
Backend Plugin	Express.js route/service on the Backstage backend
Backend Module	Extension point for existing backend plugins

Popular Official Plugins

Plugin	Function
`@backstage/plugin-catalog`	Software Catalog UI
`@backstage/plugin-scaffolder`	Template Wizard
`@backstage/plugin-techdocs`	Docs viewer
`@backstage/plugin-search`	Global search
`@backstage/plugin-kubernetes`	K8s workload viewer
`@backstage/plugin-cost-insights`	Cloud cost visibility
`@backstage/plugin-github-actions`	CI/CD pipeline view
`@backstage/plugin-pagerduty`	On-call / incident data

Creating a Custom Plugin

# Scaffold a new plugin
yarn backstage-cli new --select plugin

This generates:

plugins/
  my-plugin/
    src/
      components/
        ExampleComponent/
      index.ts
      plugin.ts
      routes.ts
    package.json

Registering a Plugin in the App

// packages/app/src/App.tsx
import { MyPluginPage } from '@internal/plugin-my-plugin';
 
const routes = (
  <FlatRoutes>
    <Route path="/my-plugin" element={<MyPluginPage />} />
  </FlatRoutes>
);

8. Authentication & Identity

Backstage supports multiple auth providers out of the box.

Supported Providers

GitHub, GitLab, Google, Microsoft Azure AD
Okta, Auth0, OneLogin, Bitbucket
Guest (development only)
Custom OIDC/SAML

Configuration (`app-config.yaml`)

auth:
  environment: production
  providers:
    github:
      production:
        clientId: ${AUTH_GITHUB_CLIENT_ID}
        clientSecret: ${AUTH_GITHUB_CLIENT_SECRET}

Backstage maps external identity (GitHub username) to an internal catalog User entity:

providers.github.create({
  signIn: {
    resolver: providers.github.resolvers.usernameMatchingUserEntityName(),
  },
})

9. Search

Backstage has a pluggable search framework with full-text search across catalog entities, TechDocs, and custom sources.

Search Engines

Engine	Use Case
`lunr`	In-memory, no infra, dev/small deployments
Elasticsearch	Production, scalable
OpenSearch	Production, AWS-compatible
Postgres	Simpler production option

Indexing Flow

Collators (gather data) → Decorators (enrich) → Index (search engine) → Query API → UI

10. Kubernetes Plugin

The Kubernetes plugin surfaces workload status for any component directly in the catalog.

Annotation Required

annotations:
  backstage.io/kubernetes-id: payment-service
  backstage.io/kubernetes-namespace: production

Features

View Deployments, Pods, ReplicaSets, StatefulSets
See pod logs and errors
Multi-cluster support
Rollout status

11. Configuration (`app-config.yaml`)

The central configuration file for Backstage:

app:
  title: My Company Developer Portal
  baseUrl: https://backstage.mycompany.com
 
organization:
  name: My Company
 
backend:
  baseUrl: https://backstage.mycompany.com
  listen:
    port: 7007
  database:
    client: pg
    connection:
      host: ${POSTGRES_HOST}
      port: ${POSTGRES_PORT}
      user: ${POSTGRES_USER}
      password: ${POSTGRES_PASSWORD}
 
catalog:
  locations:
    - type: url
      target: https://github.com/myorg/catalog/blob/main/all.yaml
    - type: github-discovery
      target: https://github.com/myorg
 
techdocs:
  builder: external
  generator:
    runIn: docker
  publisher:
    type: awsS3
    awsS3:
      bucketName: my-techdocs-bucket
      region: us-east-1
 
integrations:
  github:
    - host: github.com
      token: ${GITHUB_TOKEN}

12. Deployment

Recommended Production Setup

                  ┌──────────────┐
     Users        │   Ingress /  │
    ──────────►   │   Load Bal.  │
                  └──────┬───────┘
                         │
              ┌──────────▼──────────┐
              │   Backstage Pod(s)  │
              │  (Frontend + Backend│
              │   in one container) │
              └──────────┬──────────┘
                         │
          ┌──────────────┼──────────────┐
          │              │              │
    ┌─────▼─────┐ ┌──────▼──────┐ ┌────▼─────┐
    │ PostgreSQL│ │  Object     │ │  Redis   │
    │ (Catalog  │ │  Storage    │ │  (Cache) │
    │  + Auth)  │ │ (TechDocs)  │ │          │
    └───────────┘ └─────────────┘ └──────────┘

Docker / Kubernetes

# Build image
FROM node:18-bookworm-slim
WORKDIR /app
COPY . .
RUN yarn install --frozen-lockfile
RUN yarn tsc
RUN yarn build:backend
CMD ["node", "packages/backend", "--config", "app-config.yaml"]

13. Entity Relationships

Backstage uses declarative relationships between entities:

Domain ──contains──► System
System ──contains──► Component
Component ──provides──► API
Component ──consumes──► API
Component ──dependsOn──► Resource
Component ──ownedBy──► Group
Group ──memberOf──► Group (parent)

In YAML:

spec:
  system: checkout-system          # Component belongs to a System
  owner: payments-team             # Owned by a Group
  providesApis: [payment-api]      # Exposes an API
  consumesApis: [fraud-api]        # Consumes another API
  dependsOn:
    - resource:postgres-payments   # Depends on a Resource
    - component:notification-svc   # Depends on another Component

14. Annotations Reference

Annotation	Purpose
`github.com/project-slug`	Links entity to GitHub repo
`backstage.io/techdocs-ref`	TechDocs source location
`backstage.io/kubernetes-id`	K8s workload label
`pagerduty.com/service-id`	PagerDuty service
`sentry.io/project-slug`	Sentry project
`sonarqube.org/project-key`	SonarQube analysis
`jenkins.io/job-full-name`	Jenkins job
`lighthouse.com/website-url`	Lighthouse audit URL
`jira/project-key`	Jira project board
`opsgenie.com/component-selector`	OpsGenie alerts
`datadoghq.com/dashboard-url`	Datadog dashboard

15. Key CLI Commands

# Create a new Backstage app
npx @backstage/create-app@latest
# Start development server
yarn dev
# Add a new plugin
yarn backstage-cli new --select plugin
# Add a new backend plugin
yarn backstage-cli new --select backend-plugin
# Type check
yarn tsc
# Build
yarn build:backend
# Run tests
yarn test
# Upgrade Backstage packages
yarn backstage-cli versions:bump

16. Glossary

Term	Definition
Entity	Any item registered in the Software Catalog
Descriptor	The `catalog-info.yaml` file defining an entity
Scaffolder	Template-based project creation system
TechDocs	Docs-as-code documentation system
Plugin	A modular feature extension for Backstage
Processor	Component that processes/validates catalog entities
Provider	Component that discovers and ingests catalog entities
Collator	Search indexing component
Decorator	Enriches search documents before indexing
Location	A pointer to one or more catalog descriptor files
Lifecycle	Stage of a component: `experimental`, `production`, `deprecated`
Owner	Group or User responsible for an entity

17. Summary

┌─────────────────────────────────────────────────┐
│              Backstage at a Glance              │
├──────────────────┬──────────────────────────────┤
│ Software Catalog │ Discover & own all services  │
│ Scaffolder       │ Create new services fast     │
│ TechDocs         │ Docs live next to code       │
│ Search           │ Find anything, anywhere      │
│ Kubernetes       │ See workload health in UI    │
│ Plugins          │ Extend with 100s of plugins  │
│ Auth             │ GitHub, Google, Okta & more  │
│ Config           │ One YAML to rule them all    │
└──────────────────┴──────────────────────────────┘

Backstage turns infrastructure chaos into a single pane of glass for every developer in your organization.

backstage.io | CNCF Backstage Project | GitHub: backstage/backstage ↩

Nimendra's Notes 🪴

Explorer

Backstage

1. What Is Backstage?

Key Concepts

Demo

2. Core Problem Backstage Solves

3. Architecture Overview

4. The Software Catalog

Entity Kinds

The catalog-info.yaml File

Key Metadata Fields

How Catalog Ingestion Works

5. Software Templates (Scaffolder)

Template Structure

Built-in Scaffolder Actions

6. TechDocs

How It Works

mkdocs.yml Example

Annotation in catalog-info.yaml

TechDocs Build Modes

7. Plugins

Plugin Types

Popular Official Plugins

Creating a Custom Plugin

Registering a Plugin in the App

8. Authentication & Identity

Supported Providers

Configuration (app-config.yaml)

Sign-In Resolvers

9. Search

Search Engines

Indexing Flow

10. Kubernetes Plugin

Annotation Required

Features

11. Configuration (app-config.yaml)

12. Deployment

Recommended Production Setup

Docker / Kubernetes

13. Entity Relationships

14. Annotations Reference

15. Key CLI Commands

16. Glossary

17. Summary

Footnotes

Backlinks

Table of Contents

Graph View

The `catalog-info.yaml` File

`mkdocs.yml` Example

Annotation in `catalog-info.yaml`

Configuration (`app-config.yaml`)

11. Configuration (`app-config.yaml`)