Backstage

Spotifyによるオープンソースの内部開発者ポータルプラットフォームで、ソフトウェアカタログと開発者体験を管理する。

インストール

新しいアプリケーションの作成

コマンド	説明
npx @backstage/create-app@latest	新しいBackstageアプリケーションを作成
npx @backstage/create-app@latest --skip-install	依存関係をインストールせずにアプリを作成
cd my-backstage-app && yarn install	依存関係をインストール
yarn dev	フロントエンドとバックエンドを開発モードで起動
yarn start	フロントエンドのみを起動
yarn start-backend	バックエンドのみを起動
yarn build:backend	本番用にバックエンドをビルド
yarn build	すべてのパッケージをビルド
node_modules/.bin/backstage-cli --version	Backstage CLIのバージョンを表示

Dockerデプロイ

コマンド	説明
yarn build:backend --config ../../app-config.yaml	設定ファイル付きでバックエンドをビルド
docker build -t backstage -f packages/backend/Dockerfile .	Dockerイメージをビルド
docker run -p 7007:7007 backstage	Backstageコンテナを実行

CLIコマンド

パッケージ管理

コマンド	説明
yarn backstage-cli package start	パッケージを開発モードで起動
yarn backstage-cli package build	パッケージをビルド
yarn backstage-cli package lint	パッケージのソースコードをLint
yarn backstage-cli package test	パッケージのテストを実行
yarn backstage-cli repo build --all	モノレポのすべてのパッケージをビルド
yarn backstage-cli repo lint --all	すべてのパッケージをLint
yarn backstage-cli versions:bump	Backstage依存関係を最新にバンプ
yarn backstage-cli versions:bump --release next	次のプレリリースにバンプ
yarn backstage-cli migrate package-roles	パッケージをロール使用に移行

プラグイン作成

コマンド	説明
yarn backstage-cli create-plugin	新しいフロントエンドプラグインを作成
yarn backstage-cli create-plugin --backend	新しいバックエンドプラグインを作成
yarn backstage-cli create-plugin --id my-plugin	特定のIDでプラグインを作成
yarn new	テンプレートからインタラクティブにコンポーネントを作成

ソフトウェアカタログ

エンティティの種類

コマンド	説明
リポジトリルートにcatalog-info.yamlを追加	カタログにコンポーネントを登録
catalog-info.yamlにkind: Component	ソフトウェアコンポーネントを定義
catalog-info.yamlにkind: API	APIエンティティを定義
catalog-info.yamlにkind: System	システムグループを定義
catalog-info.yamlにkind: Domain	ビジネスドメインを定義
catalog-info.yamlにkind: Resource	インフラリソースを定義
catalog-info.yamlにkind: Group	チーム/グループを定義
catalog-info.yamlにkind: User	ユーザーを定義
catalog-info.yamlにkind: Location	他のカタログファイルを参照

エンティティプロパティ

コマンド	説明
spec.owner: team-nameを設定	エンティティの所有者を設定
spec.lifecycle: productionを設定	エンティティのライフサイクルステージを設定
spec.type: serviceを設定	コンポーネントタイプを設定（service、website、library）
spec.dependsOn: ['component:other']を設定	依存関係を定義
spec.providesApis: ['api-name']を設定	提供するAPIを宣言
spec.consumesApis: ['api-name']を設定	消費するAPIを宣言
spec.system: system-nameを設定	システムに割り当て
metadata.annotationsを統合用に設定	CI/CD、監視などに接続

catalog-info.yamlの例

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: payment-service
  description: Handles payment processing and billing
  annotations:
    github.com/project-slug: org/payment-service
    backstage.io/techdocs-ref: dir:.
    jenkins.io/job-full-name: payment-service/main
    pagerduty.com/service-id: PABC123
    sonarqube.org/project-key: org_payment-service
  tags:
    - java
    - payments
  links:
    - url: https://dashboard.example.com/payments
      title: Monitoring Dashboard
      icon: dashboard
    - url: https://wiki.example.com/payment-service
      title: Wiki
spec:
  type: service
  lifecycle: production
  owner: team-payments
  system: billing
  providesApis:
    - payment-api
  consumesApis:
    - user-api
    - notification-api
  dependsOn:
    - resource:payments-db
    - component:auth-service

APIエンティティの例

apiVersion: backstage.io/v1alpha1
kind: API
metadata:
  name: payment-api
  description: Payment processing REST API
  tags:
    - rest
    - payments
spec:
  type: openapi
  lifecycle: production
  owner: team-payments
  system: billing
  definition: |
    openapi: "3.0.0"
    info:
      title: Payment API
      version: 1.0.0
    paths:
      /payments:
        post:
          summary: Create a payment
          responses:
            "201":
              description: Payment created

SystemとDomainの例

apiVersion: backstage.io/v1alpha1
kind: System
metadata:
  name: billing
  description: Billing and payment processing system
spec:
  owner: team-payments
  domain: commerce
---
apiVersion: backstage.io/v1alpha1
kind: Domain
metadata:
  name: commerce
  description: E-commerce domain covering orders, payments, and fulfillment
spec:
  owner: group:engineering-leadership

テンプレート

テンプレートプロパティ

コマンド	説明
template.yamlにkind: Template	ソフトウェアテンプレートを定義
spec.type: serviceを設定	テンプレートがサービスを作成
spec.steps[]をテンプレートアクションに設定	スキャフォールディングステップを定義
action: fetch:template	テンプレートファイルを取得してレンダリング
action: publish:github	スキャフォールドされたリポジトリをGitHubに公開
action: publish:github:pull-request	新しいリポジトリの代わりにPRを作成
action: catalog:register	作成されたエンティティをカタログに登録
action: github:actions:dispatch	GitHub Actionsワークフローをトリガー
テンプレートで${{ parameters.name }}を使用	ユーザー入力パラメータを参照
spec.parameters[]をフォームフィールドに設定	テンプレート入力フォームを定義
パラメータでui:widget: textareaを使用	フォームフィールドウィジェットをカスタマイズ

テンプレート定義の例

apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: microservice-template
  title: Create a Microservice
  description: Scaffold a new microservice with CI/CD, monitoring, and docs
  tags:
    - recommended
    - microservice
spec:
  owner: team-platform
  type: service
  parameters:
    - title: Service Details
      required:
        - name
        - description
        - owner
      properties:
        name:
          title: Service Name
          type: string
          description: Unique name of the service
          ui:autofocus: true
          ui:options:
            rows: 5
        description:
          title: Description
          type: string
        owner:
          title: Owner
          type: string
          description: Team that owns this service
          ui:field: OwnerPicker
          ui:options:
            catalogFilter:
              kind: Group
    - title: Infrastructure
      properties:
        language:
          title: Language
          type: string
          enum: ["go", "java", "python", "typescript"]
          default: go
        database:
          title: Database
          type: string
          enum: ["postgres", "mysql", "none"]
          default: postgres
        enableMonitoring:
          title: Enable Monitoring
          type: boolean
          default: true
  steps:
    - id: fetch-base
      name: Fetch Base Template
      action: fetch:template
      input:
        url: ./skeleton
        values:
          name: ${{ parameters.name }}
          description: ${{ parameters.description }}
          owner: ${{ parameters.owner }}
          language: ${{ parameters.language }}
    - id: publish
      name: Publish to GitHub
      action: publish:github
      input:
        allowedHosts: ["github.com"]
        repoUrl: github.com?owner=my-org&repo=${{ parameters.name }}
        description: ${{ parameters.description }}
        defaultBranch: main
        repoVisibility: internal
    - id: register
      name: Register in Catalog
      action: catalog:register
      input:
        repoContentsUrl: ${{ steps['publish'].output.repoContentsUrl }}
        catalogInfoPath: /catalog-info.yaml
  output:
    links:
      - title: Repository
        url: ${{ steps['publish'].output.remoteUrl }}
      - title: Open in Catalog
        icon: catalog
        entityRef: ${{ steps['register'].output.entityRef }}

プラグイン

プラグインのインストール

コマンド	説明
yarn add @backstage/plugin-catalog	カタログプラグインをインストール
yarn add @backstage/plugin-techdocs	TechDocsプラグインをインストール
yarn add @backstage/plugin-kubernetes	Kubernetesプラグインをインストール
yarn add @backstage/plugin-github-actions	GitHub Actionsプラグインをインストール
yarn add @backstage/plugin-search	検索プラグインをインストール
yarn add @backstage/plugin-scaffolder	スキャフォールダープラグインをインストール
yarn add @backstage/plugin-api-docs	APIドキュメントプラグインをインストール
yarn add @backstage/plugin-cost-insights	コストインサイトプラグインをインストール

プラグインの登録

packages/app/src/App.tsxでフロントエンドプラグインを登録:

import { CatalogGraphPage } from '@backstage/plugin-catalog-graph';
import { TechDocsReaderPage } from '@backstage/plugin-techdocs';
import { SearchPage } from '@backstage/plugin-search';

const routes = (
  <FlatRoutes>
    <Route path="/catalog" element={<CatalogIndexPage />} />
    <Route path="/catalog/:namespace/:kind/:name" element={<CatalogEntityPage />}>
      <EntityLayout>
        <EntityLayout.Route path="/" title="Overview">
          <EntityOverviewContent />
        </EntityLayout.Route>
        <EntityLayout.Route path="/api" title="API">
          <EntityApiContent />
        </EntityLayout.Route>
        <EntityLayout.Route path="/docs" title="Docs">
          <EntityTechDocsContent />
        </EntityLayout.Route>
      </EntityLayout>
    </Route>
    <Route path="/docs" element={<TechDocsReaderPage />} />
    <Route path="/search" element={<SearchPage />} />
    <Route path="/catalog-graph" element={<CatalogGraphPage />} />
  </FlatRoutes>
);

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-catalog-backend-module-github-org'));
backend.add(import('@backstage/plugin-scaffolder-backend'));
backend.add(import('@backstage/plugin-techdocs-backend'));
backend.add(import('@backstage/plugin-search-backend'));
backend.add(import('@backstage/plugin-search-backend-module-catalog'));
backend.add(import('@backstage/plugin-search-backend-module-techdocs'));
backend.add(import('@backstage/plugin-auth-backend'));
backend.add(import('@backstage/plugin-auth-backend-module-github-provider'));
backend.add(import('@backstage/plugin-kubernetes-backend'));

backend.start();

TechDocs

TechDocs操作

コマンド	説明
npx @techdocs/cli serve	TechDocsをローカルでプレビュー
npx @techdocs/cli serve --docker-image techdocs-container	カスタムDockerイメージでサーブ
npx @techdocs/cli generate	TechDocs静的サイトを生成
npx @techdocs/cli generate --source-dir .	特定のディレクトリから生成
npx @techdocs/cli publish --publisher-type googleGcs	TechDocsをGCSに公開
npx @techdocs/cli publish --publisher-type awsS3	TechDocsをS3に公開
backstage.io/techdocs-refアノテーションを追加	エンティティのTechDocsを有効化
docs/ディレクトリとmkdocs.ymlを作成	TechDocsソースをセットアップ
設定でtechdocs.builder: 'local'を設定	ローカルTechDocsビルダーを使用
設定でtechdocs.builder: 'external'を設定	外部CI/CDビルダーを使用

TechDocs mkdocs.ymlの例

site_name: Payment Service
nav:
  - Home: index.md
  - Architecture: architecture.md
  - API Reference: api-reference.md
  - Runbooks:
      - Deployment: runbooks/deployment.md
      - Incident Response: runbooks/incident-response.md
plugins:
  - techdocs-core
markdown_extensions:
  - admonition
  - pymdownx.highlight
  - pymdownx.superfences

検索

検索のセットアップ

コマンド	説明
yarn add @backstage/plugin-search	検索フロントエンドをインストール
yarn add @backstage/plugin-search-backend	検索バックエンドをインストール
yarn add @backstage/plugin-search-backend-module-catalog	カタログ検索コレクターを追加
yarn add @backstage/plugin-search-backend-module-techdocs	TechDocs検索コレクターを追加
app-config.yamlで検索エンジンを設定	Lunr、Elasticsearch、またはPgStoreをセットアップ
設定でsearch.pgを設定	検索にPostgreSQLを使用
設定でsearch.elasticsearchを設定	検索にElasticsearchを使用

設定

コア設定

コマンド	説明
app-config.yamlを編集	メイン設定ファイル
app-config.local.yamlを編集	ローカル開発オーバーライド
app-config.production.yamlを編集	本番設定
設定でapp.baseUrlを設定	フロントエンドURLを設定
設定でbackend.baseUrlを設定	バックエンドURLを設定
設定でbackend.databaseを設定	データベース接続を設定
設定でbackend.cors.originを設定	CORSオリジンを設定
設定でauth.providersを設定	認証プロバイダーを設定
設定でcatalog.locations[]を設定	カタログエンティティソースを追加
設定でcatalog.rules[]を設定	エンティティバリデーションルールを定義
設定でintegrations.github[]を設定	GitHub統合トークンを設定

app-config.yamlの例

app:
  title: My Company Developer Portal
  baseUrl: http://localhost:3000

organization:
  name: My Company

backend:
  baseUrl: http://localhost:7007
  listen:
    port: 7007
  cors:
    origin: http://localhost:3000
    methods: [GET, HEAD, PATCH, POST, PUT, DELETE]
  database:
    client: pg
    connection:
      host: ${POSTGRES_HOST}
      port: ${POSTGRES_PORT}
      user: ${POSTGRES_USER}
      password: ${POSTGRES_PASSWORD}

integrations:
  github:
    - host: github.com
      token: ${GITHUB_TOKEN}

auth:
  environment: development
  providers:
    github:
      development:
        clientId: ${GITHUB_CLIENT_ID}
        clientSecret: ${GITHUB_CLIENT_SECRET}

catalog:
  import:
    entityFilename: catalog-info.yaml
    pullRequestBranchName: backstage-integration
  rules:
    - allow: [Component, System, API, Resource, Location, Domain, Group, User]
  locations:
    - type: url
      target: https://github.com/my-org/backstage-catalog/blob/main/all-components.yaml
    - type: github-discovery
      target: https://github.com/my-org
    - type: github-org
      target: https://github.com/my-org

techdocs:
  builder: local
  generator:
    runIn: local
  publisher:
    type: local

kubernetes:
  serviceLocatorMethod:
    type: multiTenant
  clusterLocatorMethods:
    - type: config
      clusters:
        - url: ${K8S_CLUSTER_URL}
          name: production
          authProvider: serviceAccount
          serviceAccountToken: ${K8S_TOKEN}

エンティティ関係図

関係	元	先	説明
ownerOf	Group/User	Component/API	グループがエンティティを所有
ownedBy	Component/API	Group/User	エンティティがグループに所有される
consumesApi	Component	API	コンポーネントがAPIを使用
providesApi	Component	API	コンポーネントがAPIを公開
dependsOn	Component	Component/Resource	コンポーネントが別のものに依存
dependencyOf	Component/Resource	Component	依存先である
partOf	Component	System	コンポーネントがシステムに所属
hasPart	System	Component	システムがコンポーネントを含む
parentOf	Group	Group	親チームの関係
childOf	Group	Group	子チームの関係
memberOf	User	Group	ユーザーがグループに所属
hasMember	Group	User	グループがユーザーを含む

ベストプラクティス

1. すべてのリポジトリでcatalog-info.yamlを使用する — すべてのサービス、ライブラリ、APIをカタログに登録して、完全な可視性を確保しましょう。

2. 意味のある所有権を設定する — すべてのエンティティに有効なGroupを指すownerフィールドを設定し、説明責任とルーティングを可能にしましょう。

3. エンティティに豊富なアノテーションを付ける — CI/CD、監視、PagerDuty、ドキュメントのアノテーションを追加して、カタログを真のハブにしましょう。

4. ゴールデンパス用のテンプレートを作成する — スキャフォールダーを使用して新しいサービスを作成する標準化された方法を定義し、一貫性を確保しましょう。

5. TechDocsを実装する — TechDocsプラグインとmkdocs.ymlを使用して、コードと一緒にドキュメントを保持し、生きたドキュメントを実現しましょう。

6. GitHub Discoveryを使用する — カタログロケーションでgithub-discoveryを設定し、リポジトリを自動的に検出して登録しましょう。

7. 組織をモデル化する — GroupsとUsersを定義してチーム構造を反映し、所有権追跡とチームページを有効にしましょう。

8. app-config.yamlを環境対応にする — 開発にはapp-config.local.yamlを使用し、本番のシークレットには環境変数を使用しましょう。

9. プラグインエコシステムを構築する — カスタムフロントエンドとバックエンドプラグインを作成して、組織固有のツールでBackstageを拡張しましょう。

10. SystemsとDomainsを定義する — SystemsとDomainsを使用して上位レベルのアーキテクチャをモデル化し、開発者にプラットフォームのマップを提供しましょう。