Platform EngineeringとBackstageによるInternal Developer Platform構築実践ガイド

┌──────────────────────────────────────────────────────┐
│                 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           │
└─────────────────────────────────────────────────┘

# Backstageアプリの作成
npx @backstage/create-app@latest

# プロジェクトディレクトリ構造
# my-backstage-app/
# ├── app-config.yaml           # メイン設定ファイル
# ├── app-config.production.yaml # 本番オーバーライド
# ├── catalog-info.yaml         # Backstage自体のカタログエントリ
# ├── packages/
# │   ├── app/                  # フロントエンド（React）
# │   └── backend/              # バックエンド（Node.js）
# ├── plugins/                  # カスタムプラグイン
# └── package.json

# ローカル開発サーバーの起動
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統合設定
integrations:
  github:
    - host: github.com
      token: ${GITHUB_TOKEN}

# 認証プロバイダー設定
auth:
  environment: production
  providers:
    github:
      production:
        clientId: ${AUTH_GITHUB_CLIENT_ID}
        clientSecret: ${AUTH_GITHUB_CLIENT_SECRET}

# カタログソース登録
catalog:
  import:
    entityFilename: catalog-info.yaml
    pullRequestBranchName: backstage-integration
  rules:
    - allow: [Component, System, API, Resource, Location, Template, Group, User]
  locations:
    # 組織全体のGitHubリポジトリ自動探索
    - type: github-discovery
      target: https://github.com/acme-corp/*/blob/main/catalog-info.yaml
    # テンプレート登録
    - type: file
      target: ../../templates/all-templates.yaml
    # 組織構造の同期
    - 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

# TechDocsを外部ストレージに設定
techdocs:
  builder: 'external'
  generator:
    runIn: 'local'
  publisher:
    type: 'awsS3'
    awsS3:
      bucketName: 'acme-techdocs'
      region: 'ap-northeast-2'

# catalog-info.yaml - マイクロサービス登録の例
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: order-service
  title: '注文サービス'
  description: '注文作成、決済処理、在庫引き当てを担当するコアドメインサービス'
  annotations:
    # GitHub連携
    github.com/project-slug: acme-corp/order-service
    # CI/CD連携
    backstage.io/techdocs-ref: dir:.
    github.com/workflows: build-and-deploy.yaml
    # Kubernetes連携
    backstage.io/kubernetes-id: order-service
    backstage.io/kubernetes-namespace: order
    # PagerDutyインシデント連携
    pagerduty.com/service-id: PXXXXXX
    # Datadogダッシュボード
    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仕様の登録
apiVersion: backstage.io/v1alpha1
kind: API
metadata:
  name: order-api
  description: '注文処理gRPC API'
spec:
  type: grpc
  lifecycle: production
  owner: team-order
  system: ecommerce-platform
  definition:
    $text: ./proto/order.proto
---
# データベースリソースの登録
apiVersion: backstage.io/v1alpha1
kind: Resource
metadata:
  name: order-database
  description: '注文サービスPostgreSQLデータベース'
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マイクロサービス'
  description: |
    Spring Boot 3.x + gRPCベースのマイクロサービスプロジェクトを作成します。
    含まれるもの：Dockerfile、Helm Chart、GitHub Actions CI/CD、
    Prometheusメトリクス、Health Check、catalog-info.yaml
  tags:
    - java
    - spring-boot
    - grpc
    - recommended
spec:
  owner: platform-team
  type: service

  # ユーザー入力パラメータの定義
  parameters:
    - title: 'サービス基本情報'
      required:
        - serviceName
        - owner
        - system
      properties:
        serviceName:
          title: 'サービス名'
          type: string
          description: '英小文字とハイフンのみ使用（例：order-service）'
          pattern: '^[a-z][a-z0-9-]*$'
          ui:autofocus: true
        description:
          title: 'サービス説明'
          type: string
        owner:
          title: '所有チーム'
          type: string
          ui:field: OwnerPicker
          ui:options:
            catalogFilter:
              kind: Group
        system:
          title: '所属システム'
          type: string
          ui:field: EntityPicker
          ui:options:
            catalogFilter:
              kind: System

    - title: '技術オプション'
      properties:
        javaVersion:
          title: 'Javaバージョン'
          type: string
          enum: ['17', '21']
          default: '21'
        database:
          title: 'データベース'
          type: string
          enum: ['postgresql', 'mysql', 'none']
          default: 'postgresql'
        enableKafka:
          title: 'Kafka連携'
          type: boolean
          default: false

    - title: 'インフラ設定'
      properties:
        namespace:
          title: 'K8sネームスペース'
          type: string
          default: 'default'
        cluster:
          title: 'デプロイクラスター'
          type: string
          enum: ['dev', 'staging', 'production']
          default: 'dev'

  # 実行ステップの定義
  steps:
    # 1. テンプレートからプロジェクトコードを生成
    - id: fetch-template
      name: 'プロジェクトコード生成'
      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. GitHubリポジトリの作成
    - id: publish-github
      name: 'GitHubリポジトリ作成'
      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. Backstageカタログに登録
    - id: register-catalog
      name: 'カタログ登録'
      action: catalog:register
      input:
        repoContentsUrl: ${{ steps['publish-github'].output.repoContentsUrl }}
        catalogInfoPath: /catalog-info.yaml

    # 4. ArgoCD Application作成
    - id: create-argocd-app
      name: 'ArgoCDデプロイ設定'
      action: argocd:create-resources
      input:
        appName: ${{ parameters.serviceName }}
        argoInstance: main
        namespace: ${{ parameters.namespace }}
        repoUrl: ${{ steps['publish-github'].output.remoteUrl }}
        path: deploy/helm

  # 完了後の案内
  output:
    links:
      - title: 'GitHubリポジトリ'
        url: ${{ steps['publish-github'].output.remoteUrl }}
      - title: 'カタログで確認'
        icon: catalog
        entityRef: ${{ steps['register-catalog'].output.entityRef }}

# フロントエンドプラグインの作成
cd my-backstage-app
yarn new --select plugin

# バックエンドプラグインの作成
yarn new --select backend-plugin

# 生成されたプラグイン構造
# plugins/
# └── my-custom-plugin/
#     ├── src/
#     │   ├── components/
#     │   │   └── ExampleComponent/
#     │   ├── plugin.ts          # プラグイン定義
#     │   ├── routes.ts          # ルーティング設定
#     │   └── index.ts
#     ├── dev/                   # 独立開発環境
#     │   └── 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: 'サービス', field: 'name' },
  { title: '所有チーム', field: 'owner' },
  {
    title: 'ステータス',
    field: 'status',
    render: (row: ServiceHealth) => {
      switch (row.status) {
        case 'healthy':
          return <StatusOK>正常</StatusOK>;
        case 'degraded':
          return <StatusWarning>パフォーマンス低下</StatusWarning>;
        case 'down':
          return <StatusError>障害</StatusError>;
        default:
          return null;
      }
    },
  },
  { title: 'Uptime (%)', field: 'uptime', type: 'numeric' },
  { title: 'エラー率 (%)', field: 'errorRate', type: 'numeric' },
  { title: '最後のインシデント', 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' },
        });

        // 各サービスのヘルスデータを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="サービスヘルスダッシュボード"
      columns={columns}
      data={services}
      options={{
        sorting: true,
        paging: true,
        pageSize: 20,
        search: true,
      }}
    />
  );
};

# 1. 現在のバージョン確認
yarn backstage-cli info

# 2. バージョンバンプ（依存関係の自動更新）
yarn backstage-cli versions:bump

# 3. 変更内容の確認
git diff

# 4. 型チェック
yarn tsc

# 5. テスト実行
yarn test

# 6. ビルド確認
yarn build

# 7. マイグレーションガイドの確認
# https://backstage.io/docs/getting-started/keeping-backstage-updated

# 推奨：CIで自動的にアップグレードPRを生成
# .github/workflows/backstage-upgrade.yaml
# 毎週月曜日に自動実行してバージョンバンプ後にPRを作成

# app-config.yaml - 接続プールチューニング
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