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 as an Internal Developer Portal (IDP) for a platform team, I realized it's much more—it's the front door to your entire engineering ecosystem. A well-configured IDP reduces the friction between "I need to ship something" and "it's deployed and observable."

Backstage, open-sourced by Spotify in 2020 and now a CNCF incubating project, has become the de facto standard for Internal Developer Portals. In this article, we'll build an IDP backed by GitHub, ArgoCD, Kubernetes, Prometheus, and Grafana—giving developers a single interface to discover, create, deploy, and observe services.

---

🎯 What Is an Internal Developer Portal (IDP)?

Definition

An Internal Developer Portal (IDP) is a centralized web application that provides developers with everything they need to discover, create, deploy, and observe software components within an organization. The key word is internal—an IDP is opinionated around your organization's specific toolchain and golden paths.

Backstage vs Generic Developer Portal: A generic developer portal is just a website. An IDP built with Backstage is the front-end to your entire platform—it surfaces GitHub repos, triggers ArgoCD deployments, shows Kubernetes workload health, and brings Grafana dashboards into a single pane of glass.

Core Capabilities

Capability	Description	Value	Integrated Tool
Software Catalog	Inventory of all software components	"What exists and who owns it?"	GitHub
Software Templates	Scaffolding for new projects	"How do I start something new?"	GitHub + ArgoCD
TechDocs	Documentation alongside code	"How do I use this?"	GitHub
Kubernetes Plugin	Workload visibility per component	"Is my service healthy?"	Kubernetes
ArgoCD Plugin	GitOps deployment status	"What's deployed and where?"	ArgoCD
Grafana/Prometheus	Metrics and dashboards	"How is my service performing?"	Prometheus + Grafana
Search	Find anything across the org	"Where is what I need?"	—

---

🏗️ 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>,
);

---

🌐 IDP Stack Architecture

Backstage acts as the single pane of glass in front of your entire platform. In our stack, every service deployed to Kubernetes is created via a GitHub repository, promoted through ArgoCD, and observed via Prometheus and Grafana—all surfaced through Backstage.

How Each Tool Maps to Backstage

Tool	Backstage Integration	What Developers See
GitHub	Catalog ingestion, Scaffolder publisher	Repo link, CI status, PRs
GitHub Actions	github-actions plugin	Workflow runs per component
ArgoCD	argocd plugin	Sync status, health, revision
Kubernetes	kubernetes plugin	Pods, events, logs per service
Prometheus	prometheus plugin	Alert status, custom metrics
Grafana	grafana plugin	Embedded dashboards per component

---

📚 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:
  # ...

---

🔄 ArgoCD Integration

ArgoCD is the GitOps delivery engine for our IDP. When a developer uses a Backstage Software Template to create a service, the scaffolder creates the GitHub repo and registers an ArgoCD Application—so the service is immediately deployable.

ArgoCD Application via Backstage Template

The template step that creates the ArgoCD Application (already shown in the scaffolder section above) triggers this resource in the cluster:

# argocd-application.yaml (created by Backstage Scaffolder)
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: user-service
  namespace: argocd
  labels:
    backstage.io/component: user-service
spec:
  project: default
  source:
    repoURL: https://github.com/company/user-service
    targetRevision: HEAD
    path: deploy/kubernetes
  destination:
    server: https://kubernetes.default.svc
    namespace: production
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true

ArgoCD Plugin in Backstage

Add the ArgoCD plugin to surface deployment status directly on each catalog entity page:

# Install ArgoCD plugin
yarn --cwd packages/app add @roadiehq/backstage-plugin-argo-cd
yarn --cwd packages/backend add @roadiehq/backstage-plugin-argo-cd-backend

// packages/app/src/components/catalog/EntityPage.tsx
import {
  EntityArgoCDOverviewCard,
  EntityArgoCDHistoryCard,
  isArgocdAvailable,
} from '@roadiehq/backstage-plugin-argo-cd';

// Add to your service entity page
const serviceEntityPage = (
  <EntityLayout>
    <EntityLayout.Route path="/" title="Overview">
      <Grid container spacing={3}>
        {/* ...existing cards... */}
        <EntitySwitch>
          <EntitySwitch.Case if={isArgocdAvailable}>
            <Grid item sm={12}>
              <EntityArgoCDOverviewCard />
            </Grid>
          </EntitySwitch.Case>
        </EntitySwitch>
      </Grid>
    </EntityLayout.Route>
    <EntityLayout.Route path="/argocd" title="ArgoCD">
      <EntityArgoCDHistoryCard />
    </EntityLayout.Route>
  </EntityLayout>
);

# app-config.yaml - ArgoCD backend configuration
argocd:
  username: ${ARGOCD_USERNAME}
  password: ${ARGOCD_PASSWORD}
  appLocatorMethods:
    - type: 'config'
      instances:
        - name: argocd
          url: https://argocd.internal
          token: ${ARGOCD_TOKEN}

Catalog Annotation for ArgoCD

Annotate your catalog-info.yaml to link the entity to its ArgoCD app:

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: user-service
  annotations:
    argocd/app-name: user-service          # ArgoCD Application name
    argocd/app-namespace: production       # Target namespace
    github.com/project-slug: company/user-service
    backstage.io/kubernetes-id: user-service
spec:
  type: service
  lifecycle: production
  owner: team:identity

End-to-End GitOps Flow

---

📊 Observability Integration (Prometheus & Grafana)

Every service in our IDP exposes metrics collected by Prometheus and visualized in Grafana. Backstage surfaces both—developers never need to leave the portal to check service health.

Kubernetes Plugin (Pod-Level Visibility)

yarn --cwd packages/app add @backstage/plugin-kubernetes
yarn --cwd packages/backend add @backstage/plugin-kubernetes-backend

# app-config.yaml - Kubernetes cluster config
kubernetes:
  serviceLocatorMethod:
    type: multiTenant
  clusterLocatorMethods:
    - type: config
      clusters:
        - name: production
          url: https://kubernetes.internal
          authProvider: serviceAccount
          serviceAccountToken: ${K8S_SA_TOKEN}
          caData: ${K8S_CA_DATA}
        - name: staging
          url: https://kubernetes-staging.internal
          authProvider: serviceAccount
          serviceAccountToken: ${K8S_STAGING_SA_TOKEN}
          caData: ${K8S_STAGING_CA_DATA}

Prometheus Plugin

yarn --cwd packages/app add @roadiehq/backstage-plugin-prometheus

# app-config.yaml - Prometheus configuration
prometheus:
  proxyPath: /prometheus/api
  uiUrl: https://prometheus.internal

# Backstage proxy config to reach Prometheus
proxy:
  '/prometheus/api':
    target: https://prometheus.internal/api/v1/
    headers:
      Authorization: Bearer ${PROMETHEUS_TOKEN}

Annotate services to bind Prometheus alerts and rules:

# catalog-info.yaml
metadata:
  annotations:
    prometheus.io/alert: user-service-high-error-rate  # Alert rule name
    prometheus.io/service-name: user-service            # Prometheus job label

Grafana Plugin

yarn --cwd packages/app add @k-phoen/backstage-plugin-grafana

# app-config.yaml - Grafana configuration
grafana:
  domain: https://grafana.internal
  unifiedAlerting: true

proxy:
  '/grafana/api':
    target: https://grafana.internal
    headers:
      Authorization: Bearer ${GRAFANA_TOKEN}

Annotate services to link their Grafana dashboard:

# catalog-info.yaml
metadata:
  annotations:
    grafana/dashboard-selector: "title @> 'User Service'"  # Grafana folder/title selector
    grafana/alert-label-selector: "service=user-service"   # Alert label filter

// packages/app/src/components/catalog/EntityPage.tsx
import {
  EntityGrafanaDashboardsCard,
  EntityGrafanaAlertsCard,
  isGrafanaAvailable,
} from '@k-phoen/backstage-plugin-grafana';
import {
  EntityPrometheusAlertCard,
  EntityPrometheusContent,
  isPrometheusAvailable,
} from '@roadiehq/backstage-plugin-prometheus';

const serviceEntityPage = (
  <EntityLayout>
    <EntityLayout.Route path="/monitoring" title="Monitoring">
      <Grid container spacing={3}>
        <EntitySwitch>
          <EntitySwitch.Case if={isPrometheusAvailable}>
            <Grid item sm={6}>
              <EntityPrometheusAlertCard />
            </Grid>
          </EntitySwitch.Case>
        </EntitySwitch>
        <EntitySwitch>
          <EntitySwitch.Case if={isGrafanaAvailable}>
            <Grid item sm={6}>
              <EntityGrafanaAlertsCard />
            </Grid>
            <Grid item sm={12}>
              <EntityGrafanaDashboardsCard />
            </Grid>
          </EntitySwitch.Case>
        </EntitySwitch>
      </Grid>
    </EntityLayout.Route>
  </EntityLayout>
);

Complete catalog-info.yaml for an IDP-managed Service

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: user-service
  description: Handles user authentication and profile management
  annotations:
    # GitHub
    github.com/project-slug: company/user-service
    # ArgoCD
    argocd/app-name: user-service
    # Kubernetes
    backstage.io/kubernetes-id: user-service
    backstage.io/kubernetes-namespace: production
    # Prometheus
    prometheus.io/alert: user-service-high-error-rate
    prometheus.io/service-name: user-service
    # Grafana
    grafana/dashboard-selector: "title @> 'User Service'"
    grafana/alert-label-selector: "service=user-service"
    # Docs
    backstage.io/techdocs-ref: dir:.
  tags:
    - python
    - fastapi
    - authentication
spec:
  type: service
  lifecycle: production
  owner: team:identity
  system: authentication
  dependsOn:
    - resource:users-database
  providesApis:
    - user-api

---

🔌 Plugins

Plugin Architecture

Popular Plugins

Plugin	Purpose	Integration
kubernetes	View K8s resources per component	Pods, events, logs, rollouts
argocd	GitOps deployment status	Sync state, health, revision history
github-actions	CI/CD visibility	Workflow runs, build status
prometheus	Metrics and alert status	Active alerts, custom metric graphs
grafana	Embedded dashboards	Per-service Grafana dashboards and alerts
pagerduty	Incident management	On-call info, active incidents
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

This diagram shows the full production deployment of Backstage as an IDP alongside the platform tools it integrates with:

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 that integrate seamlessly with your Backstage IDP.

---

📚 References

• What is Backstage? - Official Docs

• Backstage Software Catalog

• Backstage Software Templates

• Backstage Kubernetes Plugin

• roadiehq/backstage-plugin-argo-cd

• roadiehq/backstage-plugin-prometheus

• k-phoen/backstage-plugin-grafana

• ArgoCD GitOps Documentation

• Prometheus Operator for Kubernetes

• Backstage Community Plugins

• Road to Backstage Adoption