Platform Engineering and Building an Internal Developer Platform with Backstage: A Practical Guide

┌──────────────────────────────────────────────────────┐
│                 Developer Portal (UI)                 │
│   ┌───────────┐ ┌───────────┐ ┌───────────────────┐  │
│   │  Catalog  │ │  Scaffolder│ │  TechDocs         │  │
│   └───────────┘ └───────────┘ └───────────────────┘  │
├──────────────────────────────────────────────────────┤
│            Internal Developer Platform                │
│   ┌───────────┐ ┌───────────┐ ┌───────────────────┐  │
│   │ IaC Engine│ │ CI/CD     │ │ Policy Engine     │  │
│   │ (Terraform│ │ (GitHub   │ │ (OPA/Kyverno)     │  │
│   │  Crossplane│ │  Actions) │ │                   │  │
│   └───────────┘ └───────────┘ └───────────────────┘  │
│   ┌───────────┐ ┌───────────┐ ┌───────────────────┐  │
│   │ K8s       │ │ Observ-   │ │ Secret Mgmt       │  │
│   │ Clusters  │ │ ability   │ │ (Vault)           │  │
│   └───────────┘ └───────────┘ └───────────────────┘  │
└──────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────┐
│              Backstage App (React)               │
│  ┌─────────┐ ┌──────────┐ ┌─────────────────┐   │
│  │ Catalog │ │ Scaffolder│ │ TechDocs        │   │
│  │ Plugin  │ │ Plugin   │ │ Plugin          │   │
│  └─────────┘ └──────────┘ └─────────────────┘   │
│  ┌─────────┐ ┌──────────┐ ┌─────────────────┐   │
│  │ K8s     │ │ CI/CD    │ │ Custom Plugins  │   │
│  │ Plugin  │ │ Plugin   │ │                 │   │
│  └─────────┘ └──────────┘ └─────────────────┘   │
├─────────────────────────────────────────────────┤
│           Backstage Backend (Node.js)            │
│  ┌──────────┐ ┌───────────┐ ┌────────────────┐  │
│  │ Catalog  │ │ Scaffolder│ │ Auth Provider  │  │
│  │ Backend  │ │ Backend  │ │ (GitHub/Okta)  │  │
│  └──────────┘ └───────────┘ └────────────────┘  │
├─────────────────────────────────────────────────┤
│         Database (PostgreSQL) / Search           │
└─────────────────────────────────────────────────┘

# Create Backstage app
npx @backstage/create-app@latest

# Project directory structure
# my-backstage-app/
# ├── app-config.yaml           # Main configuration file
# ├── app-config.production.yaml # Production overrides
# ├── catalog-info.yaml         # Backstage's own catalog entry
# ├── packages/
# │   ├── app/                  # Frontend (React)
# │   └── backend/              # Backend (Node.js)
# ├── plugins/                  # Custom plugins
# └── package.json

# Start local dev server
cd my-backstage-app
yarn dev

# app-config.yaml
app:
  title: 'ACME Developer Platform'
  baseUrl: http://localhost:3000

organization:
  name: 'ACME Corp'

backend:
  baseUrl: http://localhost:7007
  listen:
    port: 7007
  database:
    client: pg
    connection:
      host: ${POSTGRES_HOST}
      port: ${POSTGRES_PORT}
      user: ${POSTGRES_USER}
      password: ${POSTGRES_PASSWORD}

# GitHub integration settings
integrations:
  github:
    - host: github.com
      token: ${GITHUB_TOKEN}

# Authentication provider settings
auth:
  environment: production
  providers:
    github:
      production:
        clientId: ${AUTH_GITHUB_CLIENT_ID}
        clientSecret: ${AUTH_GITHUB_CLIENT_SECRET}

# Catalog source registration
catalog:
  import:
    entityFilename: catalog-info.yaml
    pullRequestBranchName: backstage-integration
  rules:
    - allow: [Component, System, API, Resource, Location, Template, Group, User]
  locations:
    # Auto-discover all GitHub repos in the organization
    - type: github-discovery
      target: https://github.com/acme-corp/*/blob/main/catalog-info.yaml
    # Register templates
    - type: file
      target: ../../templates/all-templates.yaml
    # Sync organization structure
    - type: github-org
      target: https://github.com/acme-corp

# app-config.production.yaml
app:
  baseUrl: https://developer.acme.com

backend:
  baseUrl: https://developer-api.acme.com
  cors:
    origin: https://developer.acme.com

# Configure TechDocs with external storage
techdocs:
  builder: 'external'
  generator:
    runIn: 'local'
  publisher:
    type: 'awsS3'
    awsS3:
      bucketName: 'acme-techdocs'
      region: 'ap-northeast-2'

# catalog-info.yaml - Microservice registration example
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: order-service
  title: 'Order Service'
  description: 'Core domain service responsible for order creation, payment processing, and inventory deduction'
  annotations:
    # GitHub integration
    github.com/project-slug: acme-corp/order-service
    # CI/CD integration
    backstage.io/techdocs-ref: dir:.
    github.com/workflows: build-and-deploy.yaml
    # Kubernetes integration
    backstage.io/kubernetes-id: order-service
    backstage.io/kubernetes-namespace: order
    # PagerDuty incident integration
    pagerduty.com/service-id: PXXXXXX
    # Datadog dashboard
    datadoghq.com/dashboard-url: https://app.datadoghq.com/dashboard/xxx
  tags:
    - java
    - spring-boot
    - grpc
  links:
    - url: https://grafana.acme.com/d/order-svc
      title: 'Grafana Dashboard'
      icon: dashboard
    - url: https://wiki.acme.com/order-domain
      title: 'Domain Wiki'
      icon: docs
spec:
  type: service
  lifecycle: production
  owner: team-order
  system: ecommerce-platform
  providesApis:
    - order-api
  consumesApis:
    - inventory-api
    - payment-api
  dependsOn:
    - resource:order-database
    - resource:order-redis
---
# API specification registration
apiVersion: backstage.io/v1alpha1
kind: API
metadata:
  name: order-api
  description: 'Order processing gRPC API'
spec:
  type: grpc
  lifecycle: production
  owner: team-order
  system: ecommerce-platform
  definition:
    $text: ./proto/order.proto
---
# Database resource registration
apiVersion: backstage.io/v1alpha1
kind: Resource
metadata:
  name: order-database
  description: 'Order Service PostgreSQL database'
spec:
  type: database
  owner: team-order
  system: ecommerce-platform

# templates/spring-boot-service/template.yaml
apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: spring-boot-grpc-service
  title: 'Spring Boot gRPC Microservice'
  description: |
    Creates a Spring Boot 3.x + gRPC-based microservice project.
    Includes: Dockerfile, Helm Chart, GitHub Actions CI/CD,
    Prometheus metrics, Health Check, catalog-info.yaml
  tags:
    - java
    - spring-boot
    - grpc
    - recommended
spec:
  owner: platform-team
  type: service

  # Define user input parameters
  parameters:
    - title: 'Service Basic Information'
      required:
        - serviceName
        - owner
        - system
      properties:
        serviceName:
          title: 'Service Name'
          type: string
          description: 'Lowercase letters and hyphens only (e.g., order-service)'
          pattern: '^[a-z][a-z0-9-]*$'
          ui:autofocus: true
        description:
          title: 'Service Description'
          type: string
        owner:
          title: 'Owning Team'
          type: string
          ui:field: OwnerPicker
          ui:options:
            catalogFilter:
              kind: Group
        system:
          title: 'Parent System'
          type: string
          ui:field: EntityPicker
          ui:options:
            catalogFilter:
              kind: System

    - title: 'Technical Options'
      properties:
        javaVersion:
          title: 'Java Version'
          type: string
          enum: ['17', '21']
          default: '21'
        database:
          title: 'Database'
          type: string
          enum: ['postgresql', 'mysql', 'none']
          default: 'postgresql'
        enableKafka:
          title: 'Kafka Integration'
          type: boolean
          default: false

    - title: 'Infrastructure Settings'
      properties:
        namespace:
          title: 'K8s Namespace'
          type: string
          default: 'default'
        cluster:
          title: 'Deployment Cluster'
          type: string
          enum: ['dev', 'staging', 'production']
          default: 'dev'

  # Define execution steps
  steps:
    # 1. Generate project code from template
    - id: fetch-template
      name: 'Generate Project Code'
      action: fetch:template
      input:
        url: ./skeleton
        values:
          serviceName: ${{ parameters.serviceName }}
          description: ${{ parameters.description }}
          owner: ${{ parameters.owner }}
          system: ${{ parameters.system }}
          javaVersion: ${{ parameters.javaVersion }}
          database: ${{ parameters.database }}
          enableKafka: ${{ parameters.enableKafka }}
          namespace: ${{ parameters.namespace }}

    # 2. Create GitHub repository
    - id: publish-github
      name: 'Create GitHub Repository'
      action: publish:github
      input:
        allowedHosts: ['github.com']
        repoUrl: github.com?owner=acme-corp&repo=${{ parameters.serviceName }}
        description: ${{ parameters.description }}
        defaultBranch: main
        protectDefaultBranch: true
        requireCodeOwnerReviews: true
        repoVisibility: internal

    # 3. Register in Backstage catalog
    - id: register-catalog
      name: 'Register in Catalog'
      action: catalog:register
      input:
        repoContentsUrl: ${{ steps['publish-github'].output.repoContentsUrl }}
        catalogInfoPath: /catalog-info.yaml

    # 4. Create ArgoCD Application
    - id: create-argocd-app
      name: 'Configure ArgoCD Deployment'
      action: argocd:create-resources
      input:
        appName: ${{ parameters.serviceName }}
        argoInstance: main
        namespace: ${{ parameters.namespace }}
        repoUrl: ${{ steps['publish-github'].output.remoteUrl }}
        path: deploy/helm

  # Post-completion guidance
  output:
    links:
      - title: 'GitHub Repository'
        url: ${{ steps['publish-github'].output.remoteUrl }}
      - title: 'View in Catalog'
        icon: catalog
        entityRef: ${{ steps['register-catalog'].output.entityRef }}

# Create frontend plugin
cd my-backstage-app
yarn new --select plugin

# Create backend plugin
yarn new --select backend-plugin

# Generated plugin structure
# plugins/
# └── my-custom-plugin/
#     ├── src/
#     │   ├── components/
#     │   │   └── ExampleComponent/
#     │   ├── plugin.ts          # Plugin definition
#     │   ├── routes.ts          # Routing configuration
#     │   └── index.ts
#     ├── dev/                   # Standalone dev environment
#     │   └── index.tsx
#     └── package.json

// plugins/team-health-dashboard/src/plugin.ts
import { createPlugin, createRoutableExtension } from '@backstage/core-plugin-api'

export const teamHealthDashboardPlugin = createPlugin({
  id: 'team-health-dashboard',
  routes: {
    root: rootRouteRef,
  },
})

export const TeamHealthDashboardPage = teamHealthDashboardPlugin.provide(
  createRoutableExtension({
    name: 'TeamHealthDashboardPage',
    component: () => import('./components/DashboardPage').then((m) => m.DashboardPage),
    mountPoint: rootRouteRef,
  })
)

// plugins/team-health-dashboard/src/components/DashboardPage.tsx
import React, { useEffect, useState } from 'react';
import {
  Table,
  TableColumn,
  StatusOK,
  StatusError,
  StatusWarning,
  Progress,
  ResponseErrorPanel,
} from '@backstage/core-components';
import { useApi, configApiRef } from '@backstage/core-plugin-api';
import { catalogApiRef } from '@backstage/plugin-catalog-react';

interface ServiceHealth {
  name: string;
  owner: string;
  status: 'healthy' | 'degraded' | 'down';
  uptime: number;
  lastIncident: string;
  errorRate: number;
}

const columns: TableColumn<ServiceHealth>[] = [
  { title: 'Service', field: 'name' },
  { title: 'Owner', field: 'owner' },
  {
    title: 'Status',
    field: 'status',
    render: (row: ServiceHealth) => {
      switch (row.status) {
        case 'healthy':
          return <StatusOK>Healthy</StatusOK>;
        case 'degraded':
          return <StatusWarning>Degraded</StatusWarning>;
        case 'down':
          return <StatusError>Down</StatusError>;
        default:
          return null;
      }
    },
  },
  { title: 'Uptime (%)', field: 'uptime', type: 'numeric' },
  { title: 'Error Rate (%)', field: 'errorRate', type: 'numeric' },
  { title: 'Last Incident', field: 'lastIncident' },
];

export const DashboardPage = () => {
  const catalogApi = useApi(catalogApiRef);
  const [services, setServices] = useState<ServiceHealth[]>([]);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState<Error>();

  useEffect(() => {
    const fetchData = async () => {
      try {
        const entities = await catalogApi.getEntities({
          filter: { kind: 'Component', 'spec.type': 'service' },
        });

        // Fetch health data for each service from Prometheus/Datadog API
        const healthData = await Promise.all(
          entities.items.map(async entity => {
            const metrics = await fetchServiceMetrics(
              entity.metadata.name,
            );
            return {
              name: entity.metadata.name,
              owner:
                entity.spec?.owner?.toString() ?? 'unknown',
              status: metrics.status,
              uptime: metrics.uptime,
              lastIncident: metrics.lastIncident,
              errorRate: metrics.errorRate,
            };
          }),
        );

        setServices(healthData);
      } catch (e) {
        setError(e as Error);
      } finally {
        setLoading(false);
      }
    };

    fetchData();
  }, [catalogApi]);

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

  return (
    <Table
      title="Service Health Dashboard"
      columns={columns}
      data={services}
      options={{
        sorting: true,
        paging: true,
        pageSize: 20,
        search: true,
      }}
    />
  );
};

# 1. Check current version
yarn backstage-cli info

# 2. Version bump (auto-update dependencies)
yarn backstage-cli versions:bump

# 3. Review changes
git diff

# 4. Type check
yarn tsc

# 5. Run tests
yarn test

# 6. Verify build
yarn build

# 7. Check migration guide
# https://backstage.io/docs/getting-started/keeping-backstage-updated

# Recommended: Auto-generate upgrade PRs in CI
# .github/workflows/backstage-upgrade.yaml
# Runs weekly on Monday to bump versions and create PR

# app-config.yaml - Connection pool tuning
backend:
  database:
    client: pg
    connection:
      host: ${POSTGRES_HOST}
      port: ${POSTGRES_PORT}
      user: ${POSTGRES_USER}
      password: ${POSTGRES_PASSWORD}
    pool:
      min: 5
      max: 30
      acquireTimeoutMillis: 60000
      idleTimeoutMillis: 30000