Developer Portals and Backstage

📖 Introduction

The first time I saw Backstage in action at a conference demo, I thought it was just another fancy dashboard. But after implementing it for a platform team, I realized it's much more—it's the front door to your entire platform. A good developer portal reduces the friction between "I need to do something" and "I'm doing it."

Backstage, open-sourced by Spotify in 2020, has become the de facto standard for developer portals. In this article, we'll explore how to leverage it to create a unified developer experience.

---

🎯 What Is a Developer Portal?

Definition

A developer portal is a centralized web application that provides developers with everything they need to discover, create, and manage software components within an organization.

Core Capabilities

Capability	Description	Value
Software Catalog	Inventory of all software components	"What exists and who owns it?"
Software Templates	Scaffolding for new projects	"How do I start something new?"
TechDocs	Documentation alongside code	"How do I use this?"
Search	Find anything across the org	"Where is what I need?"
Plugins	Extend with custom functionality	"Can I see my dashboards here?"

---

🏗️ Backstage Architecture

High-Level Overview

Core Components

// Simplified Backstage app structure
// packages/app/src/App.tsx

import React from 'react';
import { createApp } from '@backstage/app-defaults';
import { AppRouter, FlatRoutes } from '@backstage/core-app-api';
import { CatalogIndexPage, CatalogEntityPage } from '@backstage/plugin-catalog';
import { ScaffolderPage } from '@backstage/plugin-scaffolder';
import { TechDocsIndexPage } from '@backstage/plugin-techdocs';
import { SearchPage } from '@backstage/plugin-search';

const app = createApp({
  // Configuration
  apis: [],
  plugins: [],
  themes: [],
});

const AppProvider = app.getProvider();
const AppRouter = app.getRouter();

const routes = (
  <FlatRoutes>
    <Route path="/catalog" element={<CatalogIndexPage />} />
    <Route path="/catalog/:namespace/:kind/:name" element={<CatalogEntityPage />} />
    <Route path="/create" element={<ScaffolderPage />} />
    <Route path="/docs" element={<TechDocsIndexPage />} />
    <Route path="/search" element={<SearchPage />} />
  </FlatRoutes>
);

export default app.createRoot(
  <AppProvider>
    <AppRouter>
      {routes}
    </AppRouter>
  </AppProvider>,
);

---

📚 Software Catalog

Catalog Model

The catalog organizes entities using a well-defined model:

# catalog-info.yaml - Component definition
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: user-service
  description: Handles user authentication and profile management
  labels:
    tier: backend
  annotations:
    github.com/project-slug: company/user-service
    backstage.io/techdocs-ref: dir:.
    prometheus.io/alert: user-service-alerts
    pagerduty.com/service-id: PXXXXXX
  tags:
    - python
    - fastapi
    - authentication
  links:
    - url: https://user-service.internal
      title: Service URL
    - url: https://grafana.internal/d/user-service
      title: Grafana Dashboard
spec:
  type: service
  lifecycle: production
  owner: team:identity
  system: authentication
  dependsOn:
    - resource:users-database
    - component:email-service
  providesApis:
    - user-api

Entity Kinds

Entity Relationships

# Example: System with components
---
apiVersion: backstage.io/v1alpha1
kind: System
metadata:
  name: authentication
  description: User authentication and authorization system
spec:
  owner: team:identity
  domain: user-management

---
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: auth-api
spec:
  type: service
  lifecycle: production
  owner: team:identity
  system: authentication
  providesApis:
    - auth-api

---
apiVersion: backstage.io/v1alpha1
kind: API
metadata:
  name: auth-api
  description: Authentication REST API
spec:
  type: openapi
  lifecycle: production
  owner: team:identity
  system: authentication
  definition:
    $text: ./openapi.yaml

---
apiVersion: backstage.io/v1alpha1
kind: Resource
metadata:
  name: auth-database
  description: PostgreSQL database for auth data
spec:
  type: database
  owner: team:identity
  system: authentication

Catalog Processor (Python Example)

"""
Custom catalog processor to enrich entities.
"""

from dataclasses import dataclass
from typing import Dict, List, Optional, Any
import httpx
import yaml


@dataclass
class CatalogEntity:
    """Represents a Backstage catalog entity."""
    api_version: str
    kind: str
    metadata: Dict[str, Any]
    spec: Dict[str, Any]
    
    @classmethod
    def from_yaml(cls, content: str) -> 'CatalogEntity':
        data = yaml.safe_load(content)
        return cls(
            api_version=data.get('apiVersion', 'backstage.io/v1alpha1'),
            kind=data['kind'],
            metadata=data['metadata'],
            spec=data.get('spec', {}),
        )
    
    def to_dict(self) -> Dict[str, Any]:
        return {
            'apiVersion': self.api_version,
            'kind': self.kind,
            'metadata': self.metadata,
            'spec': self.spec,
        }


class CatalogEnricher:
    """Enrich catalog entities with external data."""
    
    def __init__(self, github_token: str, k8s_api: str):
        self.github_token = github_token
        self.k8s_api = k8s_api
    
    async def enrich(self, entity: CatalogEntity) -> CatalogEntity:
        """Enrich entity with external data."""
        if entity.kind == 'Component':
            entity = await self._enrich_component(entity)
        return entity
    
    async def _enrich_component(self, entity: CatalogEntity) -> CatalogEntity:
        """Add metadata to components from external sources."""
        annotations = entity.metadata.get('annotations', {})
        
        # Enrich from GitHub
        if 'github.com/project-slug' in annotations:
            github_data = await self._fetch_github_data(
                annotations['github.com/project-slug']
            )
            entity.metadata.setdefault('labels', {})
            entity.metadata['labels']['github-stars'] = str(github_data.get('stars', 0))
            entity.metadata['labels']['open-issues'] = str(github_data.get('open_issues', 0))
        
        # Enrich from Kubernetes
        if 'kubernetes.io/deployment' in annotations:
            k8s_data = await self._fetch_k8s_status(
                annotations['kubernetes.io/deployment']
            )
            entity.metadata.setdefault('labels', {})
            entity.metadata['labels']['replicas'] = str(k8s_data.get('replicas', 0))
            entity.metadata['labels']['status'] = k8s_data.get('status', 'unknown')
        
        return entity
    
    async def _fetch_github_data(self, repo_slug: str) -> Dict[str, Any]:
        """Fetch repository data from GitHub."""
        async with httpx.AsyncClient() as client:
            response = await client.get(
                f"https://api.github.com/repos/{repo_slug}",
                headers={"Authorization": f"token {self.github_token}"}
            )
            if response.status_code == 200:
                data = response.json()
                return {
                    'stars': data.get('stargazers_count', 0),
                    'open_issues': data.get('open_issues_count', 0),
                    'language': data.get('language'),
                }
        return {}
    
    async def _fetch_k8s_status(self, deployment_name: str) -> Dict[str, Any]:
        """Fetch deployment status from Kubernetes."""
        # In real implementation, use kubernetes client
        return {
            'replicas': 3,
            'available': 3,
            'status': 'healthy',
        }


class CatalogClient:
    """Client for Backstage Catalog API."""
    
    def __init__(self, base_url: str, token: str):
        self.base_url = base_url
        self.token = token
    
    async def get_entities(
        self, 
        kind: Optional[str] = None,
        filter: Optional[Dict[str, str]] = None
    ) -> List[CatalogEntity]:
        """Query entities from catalog."""
        params = {}
        if kind:
            params['filter'] = f'kind={kind}'
        if filter:
            for key, value in filter.items():
                params['filter'] = f'{key}={value}'
        
        async with httpx.AsyncClient() as client:
            response = await client.get(
                f"{self.base_url}/api/catalog/entities",
                params=params,
                headers={"Authorization": f"Bearer {self.token}"}
            )
            response.raise_for_status()
            return [CatalogEntity(**e) for e in response.json()]
    
    async def register_location(self, url: str) -> Dict[str, Any]:
        """Register a new catalog location."""
        async with httpx.AsyncClient() as client:
            response = await client.post(
                f"{self.base_url}/api/catalog/locations",
                json={"type": "url", "target": url},
                headers={"Authorization": f"Bearer {self.token}"}
            )
            response.raise_for_status()
            return response.json()


# Usage example
async def main():
    client = CatalogClient(
        base_url="https://backstage.example.com",
        token="your-token"
    )
    
    # Get all services
    services = await client.get_entities(kind="Component")
    for service in services:
        print(f"- {service.metadata['name']} ({service.spec.get('owner', 'unknown')})")
    
    # Register new catalog location
    await client.register_location(
        "https://github.com/company/new-service/blob/main/catalog-info.yaml"
    )

---

🛠️ Software Templates

Template Structure

# templates/python-service/template.yaml
apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: python-fastapi-service
  title: Python FastAPI Service
  description: Create a new Python FastAPI microservice with all golden path components
  tags:
    - python
    - fastapi
    - recommended
spec:
  owner: team:platform
  type: service
  
  # Template parameters (user input)
  parameters:
    - title: Service Information
      required:
        - name
        - owner
      properties:
        name:
          title: Service Name
          type: string
          description: Unique name for the service
          pattern: '^[a-z][a-z0-9-]*$'
          ui:autofocus: true
        owner:
          title: Owner Team
          type: string
          description: Team that owns this service
          ui:field: OwnerPicker
          ui:options:
            allowedKinds:
              - Group
        description:
          title: Description
          type: string
          description: Brief description of the service
    
    - title: Technical Options
      properties:
        database:
          title: Database
          type: string
          enum:
            - none
            - postgres
            - mysql
          default: postgres
        cache:
          title: Enable Redis Cache
          type: boolean
          default: false
        authentication:
          title: Authentication Type
          type: string
          enum:
            - none
            - jwt
            - oauth2
          default: jwt
    
    - title: Repository Settings
      required:
        - repoUrl
      properties:
        repoUrl:
          title: Repository Location
          type: string
          ui:field: RepoUrlPicker
          ui:options:
            allowedHosts:
              - github.com
              - gitlab.com

  # Template steps
  steps:
    # Fetch and template the skeleton
    - id: fetch-base
      name: Fetch Base Template
      action: fetch:template
      input:
        url: ./skeleton
        values:
          name: ${{ parameters.name }}
          owner: ${{ parameters.owner }}
          description: ${{ parameters.description }}
          database: ${{ parameters.database }}
          cache: ${{ parameters.cache }}
          authentication: ${{ parameters.authentication }}
    
    # Add database configuration if needed
    - id: add-database
      name: Add Database Configuration
      if: ${{ parameters.database !== 'none' }}
      action: fetch:template
      input:
        url: ./database/${{ parameters.database }}
        targetPath: ./src/database
        values:
          name: ${{ parameters.name }}
    
    # Create the repository
    - id: publish
      name: Publish Repository
      action: publish:github
      input:
        allowedHosts: ['github.com']
        description: ${{ parameters.description }}
        repoUrl: ${{ parameters.repoUrl }}
        defaultBranch: main
        repoVisibility: internal
    
    # Register in catalog
    - id: register
      name: Register in Catalog
      action: catalog:register
      input:
        repoContentsUrl: ${{ steps.publish.output.repoContentsUrl }}
        catalogInfoPath: '/catalog-info.yaml'
    
    # Create initial PR for team review
    - id: create-argocd-app
      name: Create ArgoCD Application
      action: argocd:create-application
      input:
        name: ${{ parameters.name }}
        namespace: ${{ parameters.owner }}
        repoUrl: ${{ steps.publish.output.remoteUrl }}
        path: deploy/kubernetes

  # Output to display after completion
  output:
    links:
      - title: Repository
        url: ${{ steps.publish.output.remoteUrl }}
      - title: Open in catalog
        icon: catalog
        entityRef: ${{ steps.register.output.entityRef }}
      - title: ArgoCD Application
        url: https://argocd.internal/applications/${{ parameters.name }}

Template Skeleton

templates/python-service/skeleton/
├── .github/
│   └── workflows/
│       └── ci.yaml
├── deploy/
│   └── kubernetes/
│       ├── deployment.yaml
│       └── service.yaml
├── src/
│   ├── __init__.py
│   ├── main.py
│   ├── config.py
│   ├── api/
│   │   ├── __init__.py
│   │   └── routes.py
│   └── models/
│       └── __init__.py
├── tests/
│   └── test_api.py
├── catalog-info.yaml
├── Dockerfile
├── pyproject.toml
└── README.md

Skeleton File Example

# skeleton/src/main.py.njk
"""
${{ values.description | default('Service description') }}
"""

from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
{% if values.authentication == 'jwt' %}
from .auth.jwt import JWTMiddleware
{% endif %}
from .api.routes import router
from .config import settings

app = FastAPI(
    title="${{ values.name }}",
    description="${{ values.description }}",
    version="0.1.0",
)

# CORS configuration
app.add_middleware(
    CORSMiddleware,
    allow_origins=settings.allowed_origins,
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

{% if values.authentication == 'jwt' %}
# JWT Authentication
app.add_middleware(JWTMiddleware)
{% endif %}

# Include API routes
app.include_router(router, prefix="/api/v1")


@app.get("/health")
async def health_check():
    """Health check endpoint."""
    return {"status": "healthy", "service": "${{ values.name }}"}


@app.get("/ready")
async def readiness_check():
    """Readiness check endpoint."""
    {% if values.database != 'none' %}
    # Check database connection
    from .database import check_connection
    db_ok = await check_connection()
    {% else %}
    db_ok = True
    {% endif %}
    
    {% if values.cache %}
    # Check Redis connection
    from .cache import check_redis
    cache_ok = await check_redis()
    {% else %}
    cache_ok = True
    {% endif %}
    
    return {
        "status": "ready" if (db_ok and cache_ok) else "not_ready",
        "checks": {
            "database": db_ok,
            "cache": cache_ok,
        }
    }


if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8080)

---

📖 TechDocs

Documentation as Code

TechDocs integrates documentation directly with your code using MkDocs:

# mkdocs.yaml in your service repository
site_name: User Service Documentation
site_description: Documentation for the User Service

nav:
  - Home: index.md
  - Getting Started:
      - Installation: getting-started/installation.md
      - Configuration: getting-started/configuration.md
      - Quick Start: getting-started/quick-start.md
  - API Reference:
      - Authentication: api/authentication.md
      - Users: api/users.md
      - Errors: api/errors.md
  - Architecture:
      - Overview: architecture/overview.md
      - Data Model: architecture/data-model.md
      - Integrations: architecture/integrations.md
  - Operations:
      - Deployment: operations/deployment.md
      - Monitoring: operations/monitoring.md
      - Troubleshooting: operations/troubleshooting.md

plugins:
  - techdocs-core

markdown_extensions:
  - admonition
  - codehilite
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_div_format
  - pymdownx.tabbed

TechDocs Annotation

# catalog-info.yaml
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: user-service
  annotations:
    # Point to docs in same repo
    backstage.io/techdocs-ref: dir:.
    # Or external URL
    # backstage.io/techdocs-ref: url:https://github.com/company/user-service
spec:
  # ...

---

🔌 Plugins

Plugin Architecture

Popular Plugins

Plugin	Purpose	Integration
kubernetes	View K8s resources	Cluster status, pods, logs
github-actions	CI/CD visibility	Workflow status, runs
pagerduty	Incident management	On-call info, incidents
prometheus	Metrics	Alerts, graphs
sonarqube	Code quality	Quality gates, issues
cost-insights	Cloud costs	Spending, trends
security-insights	Security posture	Vulnerabilities, compliance

Custom Plugin Example

// plugins/platform-status/src/plugin.ts
import {
  createPlugin,
  createRoutableExtension,
} from '@backstage/core-plugin-api';

export const platformStatusPlugin = createPlugin({
  id: 'platform-status',
  routes: {
    root: rootRouteRef,
  },
});

export const PlatformStatusPage = platformStatusPlugin.provide(
  createRoutableExtension({
    name: 'PlatformStatusPage',
    component: () =>
      import('./components/PlatformStatusPage').then(m => m.PlatformStatusPage),
    mountPoint: rootRouteRef,
  }),
);

// plugins/platform-status/src/components/PlatformStatusPage.tsx
import React, { useEffect, useState } from 'react';
import {
  Content,
  Header,
  Page,
  Progress,
  StatusOK,
  StatusWarning,
  StatusError,
} from '@backstage/core-components';
import { useApi, configApiRef } from '@backstage/core-plugin-api';

interface PlatformService {
  name: string;
  status: 'healthy' | 'degraded' | 'down';
  latency: number;
  lastCheck: string;
}

export const PlatformStatusPage = () => {
  const [services, setServices] = useState<PlatformService[]>([]);
  const [loading, setLoading] = useState(true);
  const config = useApi(configApiRef);
  const backendUrl = config.getString('backend.baseUrl');

  useEffect(() => {
    fetch(`${backendUrl}/api/platform-status/services`)
      .then(res => res.json())
      .then(data => {
        setServices(data);
        setLoading(false);
      });
  }, [backendUrl]);

  const getStatusComponent = (status: string) => {
    switch (status) {
      case 'healthy':
        return <StatusOK>Healthy</StatusOK>;
      case 'degraded':
        return <StatusWarning>Degraded</StatusWarning>;
      case 'down':
        return <StatusError>Down</StatusError>;
      default:
        return null;
    }
  };

  if (loading) {
    return <Progress />;
  }

  return (
    <Page themeId="tool">
      <Header title="Platform Status" subtitle="Real-time platform health" />
      <Content>
        <table>
          <thead>
            <tr>
              <th>Service</th>
              <th>Status</th>
              <th>Latency</th>
              <th>Last Check</th>
            </tr>
          </thead>
          <tbody>
            {services.map(service => (
              <tr key={service.name}>
                <td>{service.name}</td>
                <td>{getStatusComponent(service.status)}</td>
                <td>{service.latency}ms</td>
                <td>{service.lastCheck}</td>
              </tr>
            ))}
          </tbody>
        </table>
      </Content>
    </Page>
  );
};

---

🚀 Deployment Considerations

Production Architecture

Kubernetes Deployment

# deploy/backstage-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: backstage
  labels:
    app: backstage
spec:
  replicas: 2
  selector:
    matchLabels:
      app: backstage
  template:
    metadata:
      labels:
        app: backstage
    spec:
      serviceAccountName: backstage
      containers:
        - name: backstage
          image: backstage:latest
          ports:
            - containerPort: 7007
          env:
            - name: POSTGRES_HOST
              valueFrom:
                secretKeyRef:
                  name: backstage-db
                  key: host
            - name: POSTGRES_USER
              valueFrom:
                secretKeyRef:
                  name: backstage-db
                  key: username
            - name: POSTGRES_PASSWORD
              valueFrom:
                secretKeyRef:
                  name: backstage-db
                  key: password
            - name: GITHUB_TOKEN
              valueFrom:
                secretKeyRef:
                  name: backstage-github
                  key: token
          resources:
            requests:
              memory: "512Mi"
              cpu: "250m"
            limits:
              memory: "1Gi"
              cpu: "500m"
          livenessProbe:
            httpGet:
              path: /healthcheck
              port: 7007
            initialDelaySeconds: 30
            periodSeconds: 10
          readinessProbe:
            httpGet:
              path: /healthcheck
              port: 7007
            initialDelaySeconds: 5
            periodSeconds: 5

---

✅ Best Practices

Catalog Management

1. Automate discovery - Use GitHub discovery or similar

2. Enforce ownership - Every entity must have an owner

3. Keep it current - Automated health checks for stale entities

4. Start simple - Add complexity gradually

Template Design

1. Provide sensible defaults - Minimize required decisions

2. Follow golden paths - Templates encode best practices

3. Include everything - CI/CD, docs, monitoring from day one

4. Test templates - Validate template output regularly

Adoption Strategy

1. Start with catalog - Show value with visibility first

2. Add templates gradually - One use case at a time

3. Integrate existing tools - Don't replace, unify

4. Gather feedback - Iterate based on developer needs

---

🔗 What's Next?

In Article 9: Platform APIs and Abstractions, we'll explore how to design and implement platform APIs using Kubernetes operators, Crossplane, and API-first design principles.

---

📚 References

• Backstage.io Documentation

• Backstage GitHub Repository

• Spotify Engineering Blog

• Backstage Community Plugins

• Road to Backstage Adoption