Backstage: Build an Internal Developer Portal on Kubernetes

What Is Backstage?

Backstage is Spotify’s open-source developer portal — now a CNCF Incubating project. It provides a single pane of glass for all your services, documentation, APIs, and infrastructure. 29K+ GitHub stars.

Core Features

1. Software Catalog

Every service, library, and resource in one searchable catalog:

# catalog-info.yaml (lives in each repo)
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: payment-service
  description: Handles all payment processing
  annotations:
    github.com/project-slug: myorg/payment-service
    backstage.io/techdocs-ref: dir:.
  tags:
    - python
    - payments
spec:
  type: service
  lifecycle: production
  owner: team-payments
  system: checkout
  dependsOn:
    - resource:payments-db
    - component:auth-service
  providesApis:
    - payments-api

2. Software Templates (Scaffolding)

Create new services from templates:

apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: python-fastapi-service
  title: Python FastAPI Service
spec:
  owner: platform-team
  type: service
  parameters:
    - title: Service Info
      properties:
        name:
          title: Service Name
          type: string
        owner:
          title: Owner Team
          type: string
          ui:field: OwnerPicker
    - title: Infrastructure
      properties:
        database:
          title: Database
          type: string
          enum: [postgres, mysql, none]
  steps:
    - id: fetch-template
      action: fetch:template
      input:
        url: ./skeleton
        values:
          name: ${{ parameters.name }}
    - id: publish
      action: publish:github
      input:
        repoUrl: github.com?owner=myorg&repo=${{ parameters.name }}
    - id: register
      action: catalog:register
      input:
        repoContentsUrl: ${{ steps.publish.output.repoContentsUrl }}

3. TechDocs (Documentation)

Auto-publish MkDocs from every repo:

# mkdocs.yml in your service repo
site_name: Payment Service
nav:
  - Home: index.md
  - Architecture: architecture.md
  - API Reference: api.md
  - Runbook: runbook.md

plugins:
  - techdocs-core

4. Kubernetes Plugin

See pod status, deployments, and logs for every service:

# catalog-info.yaml annotation
metadata:
  annotations:
    backstage.io/kubernetes-id: payment-service
    backstage.io/kubernetes-namespace: payments

Kubernetes Deployment

apiVersion: apps/v1
kind: Deployment
metadata:
  name: backstage
  namespace: backstage
spec:
  replicas: 2
  template:
    spec:
      containers:
        - name: backstage
          image: myregistry/backstage:latest
          ports:
            - containerPort: 7007
          env:
            - name: POSTGRES_HOST
              value: "postgres.backstage.svc"
            - name: POSTGRES_PORT
              value: "5432"
            - name: GITHUB_TOKEN
              valueFrom:
                secretKeyRef:
                  name: backstage-secrets
                  key: github-token
          resources:
            requests:
              memory: "512Mi"
              cpu: "500m"

Plugin Ecosystem

Who Needs Backstage?

The value scales with complexity — more services, more teams, more value.

Related Articles

• Crossplane: Cloud Infrastructure from K8s
• Argo CD: GitOps Deployment
• Terraform vs OpenTofu