Backstageの中核コンセプト
Backstageの概要で全体像を掴んだうえで、本ドキュメントでは Backstage を運用・拡張する前に開発者が共通理解として持つべき中核概念を解説します。
1. Software Catalog
Software Catalog（ソフトウェアカタログ） は Backstage の心臓部です。組織内のすべてのソフトウェア（サービス・API・ライブラリ・インフラ・所有者）を Entity（エンティティ） という単位で一元管理します。
カタログへの取り込みフロー
カタログは、各リポジトリに置かれた catalog-info.yaml を起点にデータを取り込みます。
- Entity Provider — どこから Entity を取得するか（GitHub の特定 org、静的ファイル等）を定義する。
- Processor — 取り込んだ Entity を検証し、
annotationsの解決や Entity 間の関係（リレーション）を構築する。 - 取り込みは定期的に再実行され、
catalog-info.yamlの変更が反映される。
2. Entityモデル（Kind）
すべての Entity は kind（種別） を持ちます。代表的な Kind は以下の通りです。
| Kind | 意味 | 例 |
|---|---|---|
| Component | デプロイ・実行可能なソフトウェアの単位 | マイクロサービス、Webアプリ、ライブラリ |
| API | Component が公開/利用するインターフェース | REST、gRPC、GraphQL |
| Resource | Component が依存するインフラ | データベース、ストレージ、キュー |
| System | 関連する Component / API / Resource のまとまり | 「決済システム」 |
| Domain | System を束ねる上位のビジネス領域 | 「EC事業」 |
| Group | チーム・組織単位 | 「決済チーム」 |
| User | 個人 | 開発者アカウント |
| Location | 他の Entity の供給元を指す特殊な Kind | catalog-info.yaml の置き場所 |
Entity 間の関係（リレーション）
Entity は互いに関係を持ち、依存関係やオーナーシップをグラフとして可視化できます。
主なリレーション: ownerOf / ownedBy、partOf / hasPart、dependsOn / dependencyOf、providesApi / consumesApi。
3. catalog-info.yaml の書き方
catalog-info.yaml は各リポジトリのルートに配置する、Entity を定義するファイルです。
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
name: payment-api
namespace: default
description: 決済処理を担うマイクロサービス
tags:
- dotnet
- payments
annotations:
github.com/project-slug: my-org/payment-api
backstage.io/techdocs-ref: dir:.
backstage.io/kubernetes-id: payment-api
links:
- url: https://dashboards.example.com/payment
title: 運用ダッシュボード
spec:
type: service
lifecycle: production
owner: group:payment-team
system: payment-system
providesApis:
- payment-rest-api
dependsOn:
- resource:payments-db
主要フィールド
| フィールド | 役割 |
|---|---|
metadata.name | Entity の一意な名前（必須） |
metadata.namespace | 名前空間。省略時は default |
metadata.annotations | 外部システム連携のキー（GitHub、TechDocs、Kubernetes 等） |
metadata.tags | 検索・絞り込み用のタグ |
spec.type | Component の種類（service / website / library 等） |
spec.lifecycle | ライフサイクル（experimental / production / deprecated） |
spec.owner | オーナー（Group または User）— オーナーシップの要 |
annotations は各プラグインが外部システムと紐付くためのキーです。例えば backstage.io/kubernetes-id を付けると Kubernetes プラグインが該当 Pod を表示します。詳細はプラグインの使い方を参照。
4. TechDocs（docs-as-code）
TechDocs は、ドキュメントをコードと同じリポジトリで管理する docs-as-code の仕組みです。
- MkDocs をベースに、Markdown から静的サイトを生成する。
mkdocs.ymlとdocs/ディレクトリをリポジトリに置き、catalog-info.yamlのbackstage.io/techdocs-refアノテーションで紐付ける。- 生成された HTML は S3 / Azure Blob などのストレージに保存し、Backstage から配信する（本番推奨構成）。
ドキュメントがコードと同じ場所・同じレビューフローで更新されるため、陳腐化しにくいのが利点です。
5. Search
Search はカタログ・TechDocs・その他プラグインのコンテンツを横断的に検索する機能です。
| 検索バックエンド | 用途 |
|---|---|
| Lucene（インメモリ） | 開発・小規模。設定不要だが再起動で消える |
| PostgreSQL | 中規模。既存DBを流用できる |
| Elasticsearch / OpenSearch | 大規模・高機能。本番推奨 |
検索対象は Collator によってインデックス化され、定期的に更新されます。
6. 認証・認可・権限
認証（Authentication）
Backstage は外部 IdP と連携してユーザーを認証します。
- 対応プロバイダ例: OIDC、GitHub、GitLab、Google、Microsoft Entra ID など。
- 認証で得た ID は、カタログ上の User / Group Entity とマッピングされ、オーナーシップ表示などに使われる。
関連: OAuth / OpenID Connect、Bearer 認証。
認可（Permission Framework）
Permission Framework により、「誰がどの Entity を編集できるか」「どのテンプレートを実行できるか」といったアクセス制御をポリシーとして定義できます。
- ポリシーはコード（TypeScript）で記述する。
- ロールベース（例: オーナーのみ編集可）の制御が可能。
7. データ永続化
| 環境 | データベース | 備考 |
|---|---|---|
| 開発 | SQLite（インメモリ可） | 設定不要・再起動で消える |
| 本番 | PostgreSQL | 必須。カタログ・権限・各プラグインのデータを保持 |
バックアップ対象は PostgreSQL と TechDocs ストレージ です。運用詳細はBackstageの運用を参照してください。
ベストプラクティス
- Entity 命名規則・namespace 設計 — 命名規則を最初に決め、衝突や混乱を防ぐ。
- オーナーシップ必須化 —
spec.ownerのない Entity を許可しない運用ルールを設け、カタログ品質を担保する。 - annotations の標準化 — 連携に使うアノテーションをテンプレートで自動付与し、記述漏れを防ぐ（Software Templates参照）。