Backstage運用実践 — TechDocs、プラグイン開発、本番チェックリスト

# mkdocs.yml (リポジトリルート)
site_name: payment-api
site_description: 決済APIサービスのドキュメント

nav:
  - はじめに: index.md
  - アーキテクチャ: architecture.md
  - 運用ガイド: runbook.md
  - オンボーディング: onboarding.md

plugins:
  - techdocs-core

payment-api/
├── catalog-info.yaml      # backstage.io/techdocs-ref: dir:. アノテーション
├── mkdocs.yml
└── docs/
    ├── index.md
    ├── architecture.md
    ├── runbook.md
    └── onboarding.md

  開発者がPRをマージ
       |
       v
  CI (GitHub Actions)
       |  techdocs-cli generate   (MkDocsビルド)
       |  techdocs-cli publish    (S3アップロード)
       v
  S3バケット (techdocs-bucket)
       ^
       |  読み取り専用
  Backstage TechDocs Backend ---> ユーザーのブラウザ

# .github/workflows/techdocs.yaml
name: techdocs
on:
  push:
    branches: [main]
    paths: ['docs/**', 'mkdocs.yml']
jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - name: Install tooling
        run: |
          pip install mkdocs-techdocs-core
          npm install -g @techdocs/cli
      - name: Generate docs
        run: techdocs-cli generate --no-docker
      - name: Publish to S3
        env:
          AWS_ACCESS_KEY_ID: ${{ secrets.TECHDOCS_AWS_KEY }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.TECHDOCS_AWS_SECRET }}
        run: |
          techdocs-cli publish \
            --publisher-type awsS3 \
            --storage-name techdocs-bucket \
            --entity default/Component/payment-api

# app-config.yaml
techdocs:
  builder: 'external'        # バックエンドのビルドを無効化
  publisher:
    type: 'awsS3'
    awsS3:
      bucketName: techdocs-bucket
      region: ap-northeast-2

+------------------- Backstageモノレポ (yarn workspaces) --------------------------+
|                                                                                 |
|  packages/app  (フロントエンドシェル)      packages/backend (バックエンドシェル)      |
|  +--------------------------+           +-----------------------------+         |
|  | React SPA                |           | Node.js                     |         |
|  | - プラグインページのルーティング|  HTTP    | - プラグイン別ルーターをmount   |         |
|  | - エンティティページのタブ/カード| <-------> | - DB/キャッシュ/スケジューラ提供 |         |
|  +--------------------------+           +-----------------------------+         |
|                                                                                 |
|  plugins/                                                                       |
|  ├── my-plugin           (フロントエンドプラグイン: Reactコンポーネント)              |
|  ├── my-plugin-backend   (バックエンドプラグイン: REST API、DBアクセス)              |
|  └── my-plugin-common    (共有型、isomorphicコード)                               |
+---------------------------------------------------------------------------------+

// packages/backend/src/index.ts (新バックエンドシステム)
import { createBackend } from '@backstage/backend-defaults';

const backend = createBackend();

backend.add(import('@backstage/plugin-app-backend'));
backend.add(import('@backstage/plugin-catalog-backend'));
backend.add(import('@backstage/plugin-scaffolder-backend'));
backend.add(import('@backstage/plugin-techdocs-backend'));
backend.add(import('@backstage/plugin-auth-backend'));
backend.add(import('@backstage/plugin-permission-backend'));
// 社内カスタムプラグイン
backend.add(import('@internal/plugin-deploy-board-backend'));

backend.start();

yarn new   # メニューから plugin / backend-plugin を選択

// plugins/deploy-board-backend/src/plugin.ts
import {
  coreServices,
  createBackendPlugin,
} from '@backstage/backend-plugin-api';
import { createRouter } from './router';

export const deployBoardPlugin = createBackendPlugin({
  pluginId: 'deploy-board',
  register(env) {
    env.registerInit({
      deps: {
        logger: coreServices.logger,
        httpRouter: coreServices.httpRouter,
        database: coreServices.database,
      },
      async init({ logger, httpRouter, database }) {
        httpRouter.use(await createRouter({ logger, database }));
      },
    });
  },
});

// plugins/deploy-board-backend/src/router.ts
import { Router } from 'express';
import express from 'express';

export async function createRouter(options: {
  logger: any;
  database: any;
}): Promise<Router> {
  const router = Router();
  router.use(express.json());

  // デプロイイベントの収集 (CDパイプラインが呼び出す)
  router.post('/deployments', async (req, res) => {
    const { component, environment, version, status } = req.body;
    options.logger.info(`deployment: ${component} ${version} -> ${environment}`);
    // databaseハンドルからknexインスタンスを取得して保存
    const knex = await options.database.getClient();
    await knex('deployments').insert({
      component,
      environment,
      version,
      status,
      deployed_at: new Date(),
    });
    res.status(201).json({ ok: true });
  });

  // コンポーネント別の最新デプロイ照会 (フロントエンドが呼び出す)
  router.get('/deployments/:component', async (req, res) => {
    const knex = await options.database.getClient();
    const rows = await knex('deployments')
      .where({ component: req.params.component })
      .orderBy('deployed_at', 'desc')
      .limit(20);
    res.json(rows);
  });

  return router;
}

// plugins/deploy-board/src/components/DeployBoardCard.tsx
import React from 'react';
import { useEntity } from '@backstage/plugin-catalog-react';
import { useApi, fetchApiRef, discoveryApiRef } from '@backstage/core-plugin-api';
import useAsync from 'react-use/lib/useAsync';
import { InfoCard, Table } from '@backstage/core-components';

export const DeployBoardCard = () => {
  const { entity } = useEntity();
  const fetchApi = useApi(fetchApiRef);
  const discoveryApi = useApi(discoveryApiRef);

  const { value, loading, error } = useAsync(async () => {
    const baseUrl = await discoveryApi.getBaseUrl('deploy-board');
    const res = await fetchApi.fetch(
      `${baseUrl}/deployments/${entity.metadata.name}`,
    );
    return res.json();
  }, [entity.metadata.name]);

  if (error) return <InfoCard title="デプロイ状況">取得失敗</InfoCard>;

  return (
    <InfoCard title="デプロイ状況">
      <Table
        isLoading={loading}
        options={{ paging: false, search: false }}
        columns={[
          { title: '環境', field: 'environment' },
          { title: 'バージョン', field: 'version' },
          { title: 'ステータス', field: 'status' },
          { title: 'デプロイ時刻', field: 'deployed_at' },
        ]}
        data={value ?? []}
      />
    </InfoCard>
  );
};

// packages/backend/src/extensions/permissionPolicy.ts
import { createBackendModule } from '@backstage/backend-plugin-api';
import { policyExtensionPoint } from '@backstage/plugin-permission-node/alpha';
import {
  PermissionPolicy,
  PolicyQuery,
  PolicyQueryUser,
} from '@backstage/plugin-permission-node';
import {
  AuthorizeResult,
  PolicyDecision,
  isPermission,
} from '@backstage/plugin-permission-common';
import { catalogEntityDeletePermission } from '@backstage/plugin-catalog-common/alpha';

class AcmePermissionPolicy implements PermissionPolicy {
  async handle(
    request: PolicyQuery,
    user?: PolicyQueryUser,
  ): Promise<PolicyDecision> {
    // カタログエンティティの削除はplatform-teamのみ許可
    if (isPermission(request.permission, catalogEntityDeletePermission)) {
      const isPlatformTeam = user?.info.ownershipEntityRefs.includes(
        'group:default/platform-team',
      );
      return {
        result: isPlatformTeam ? AuthorizeResult.ALLOW : AuthorizeResult.DENY,
      };
    }
    return { result: AuthorizeResult.ALLOW };
  }
}

export const permissionModuleAcmePolicy = createBackendModule({
  pluginId: 'permission',
  moduleId: 'acme-policy',
  register(reg) {
    reg.registerInit({
      deps: { policy: policyExtensionPoint },
      async init({ policy }) {
        policy.setPolicy(new AcmePermissionPolicy());
      },
    });
  },
});

permission:
  enabled: true

# すべての@backstageパッケージを目標リリースへバンプ
yarn backstage-cli versions:bump

# 変更されたパッケージ間の重複/衝突を点検
yarn backstage-cli versions:check

# ビルドとテストで検証
yarn tsc && yarn build:all && yarn test:all

backend:
  cache:
    store: redis
    connection: redis://backstage-redis:6379

レベル0  インストール済み   デモインスタンス、手動登録エンティティ数個
レベル1  カタログ稼働      ディスカバリ自動化、オーナーシップモデル、認証連携 [第1回]
レベル2  セルフサービス    ゴールデンパステンプレート、day-2アクション、
                         採用率測定                                  [第2回]
レベル3  ナレッジハブ      TechDocs全面展開、エコシステムプラグイン、検索定着 [第3回]
レベル4  運用成熟         権限ポリシー、SLO運用、貢献モデル、定期アップグレード [第3回]
レベル5  標準プラットフォーム ポータル経由がデフォルトの経路、指標ベースの継続改善