Backstageで開発者ポータル構築：サービスカタログから始める
組織内に多数のサービスが存在すると、「どのサービスが誰の管理下にあるか」「ドキュメントはどこにあるか」を 把握するだけでも一苦労になる。Backstage（オープンソースの開発者ポータルフレームワーク）を導入することで、 サービスカタログとドキュメントを一元管理し、組織全体のDevExを底上げできる。
背景・現状の課題
開発者ポータルを構築しようとする組織の多くが直面する課題は、サービスカタログ管理ツールが チームごとにバラバラであることと、ドキュメントの整理・更新にかかる手間が大きいことである。 情報が分散していると、新しく参加したメンバーが必要な情報にたどり着くまでに時間がかかる。
Backstage導入の3つのステップ
| ステップ | 内容 | ポイント |
|---|---|---|
| 1. サービスカタログの構築 | 各サービスのオーナー・技術スタック・依存関係を`catalog-info.yaml`として定義 | 既存サービスを一括で登録するスクリプトを用意すると移行が楽になる |
| 2. TechDocsの統合 | 各サービスのMarkdownドキュメントをBackstage上で一元表示 | ドキュメントはサービスのリポジトリと同じ場所で管理し、Backstage側は表示のみ担当させる |
| 3. 外部ツールとの統合 | ArgoCD・Kubernetes等のプラグインで、デプロイ状況やリソース状態をポータル上に統合表示 | まずは頻繁に参照するツールから段階的にプラグインを追加する |
実装上の落とし穴と対策
Backstage導入で失敗しやすいのは、最初から全サービスの詳細情報を完璧に登録しようとして プロジェクトが長期化してしまうケースである。まずは最小限の情報（サービス名・オーナー・リポジトリURL） だけでカタログを立ち上げ、実際に使われ始めてから情報を充実させていく方が、定着までのスピードが速い。
組織への浸透のさせ方
Backstageを構築しても、開発者が日常的に開くツールにならなければ効果は出ない。新規サービス作成時の テンプレート機能をBackstage経由でのみ提供する、オンボーディング資料をBackstageに集約するなど、 「Backstageを見ないと困る」状況を意図的に作ることで、利用習慣として定着しやすくなる。
まとめ
Backstageによる開発者ポータルは、サービスカタログとドキュメントの一元管理を通じて組織のDevExを 向上させる。完璧な情報整備を最初から目指すのではなく、最小限のカタログから始めて段階的に 充実させていく進め方が、実際の定着につながりやすい。
公式ドキュメント: Backstage Documentation
