内製PaaS（Backstage）の基本と導入シナリオ

Backstageとは：ソフトウェアを“見える化”する開発者ポータルの基盤

Backstageは、社内に散らばるサービスやライブラリ、データパイプラインを「ソフトウェアカタログ」に登録し、横断的に検索・依存関係の把握・ドキュメント閲覧・新規サービス作成までを一つのUIから行えるオープンソースフレームワークです。 各リポジトリにcatalog-info.yamlを配置し、必要なメタデータを記載すれば、ポータルで一元的に可視化できます。TechDocs（docs-like-code）を利用するとMarkdownベースのドキュメントも同じ仕組みに取り込めるため、「情報が散在して見つからない」という課題が大きく改善されます。

まずは「一覧・所有者・依存関係・ドキュメントが一箇所に揃っている状態」を作ることが、社内導入の最初の成功体験になります。

SpotifyがBackstageをOSS化した背景には「社内に点在するインフラやCI/CDのツールを一つのUIに集約したい」という目的があります。Backstageは単なる情報ポータルではなく、「社内標準（命名規則・テンプレート・運用導線）を配布する仕組み」として機能する点が、多拠点・多技術スタックの現場で特に効果を発揮します。

コミュニティと信頼性：CNCF配下で成熟し、導入実績も拡大

Backstageは2020年9月にCNCF Sandboxへ登録され、2022年3月にはIncubatingへ昇格しました。これはOSSとしての信頼性やエコシステムの広がりを示す重要な出来事です。CNCF公式ブログやプロジェクトページでは、採用企業の事例が多数紹介されており、すでに大規模組織での利用が進んでいることが確認できます。

社内稟議の際は「CNCF配下で標準化が進んでいること」「プラグインエコシステムが拡大していること」を強調すると合意が得やすくなります。また、Backstage公式サイトでも「数千社規模の採用事例」「プラグインの増加」などが紹介されており、評価時にはOSSとしての健全性（更新頻度、貢献者数、ロードマップ）を一次情報で確認することが大切です。

Backstageが解決する課題：オンボーディング、標準化、自動化の基盤に

Backstageは、以下のような場面で特に効果を発揮します。

• 新入メンバーが「どこに何があるのか分からない」状態を改善

• 既存メンバーが「毎回正しい作り方を思い出す」手間を削減

• サービス作成からCI設定、マニフェスト準備、カタログ登録までをテンプレート化して自動化

テンプレート（Scaffolder）から新規サービスを作成すれば、初期設定が自動化され、Golden Path（推奨経路）に沿った環境をすぐに整備できます。さらにKubernetesや監視ツールと連携させることで、開発から運用までの導線を一元化することが可能になります。

出典：Backstage公式「Catalog Descriptor Format（catalog-info.yamlの仕様）」
出典：Backstage公式「TechDocs（docs-like-code）」
出典：Spotify Engineering「What the Heck is Backstage Anyway?」
出典：CNCF「Backstage Project Page」
出典：CNCF Blog「Backstage project joins the CNCF Incubator」
出典：Backstage公式サイト

内製PaaS（Backstage）の導入手順：最小構成からPoC、本番へ

まずはローカルで“動かす”：create-appで感触を掴む

導入の第一歩はローカル環境でBackstageを動かすことです。公式ドキュメントの「Creating your Backstage App」に沿えば、SQLiteとサンプルデータが組み込まれたBackstageを立ち上げられます。これは本番構成ではありませんが、ソフトウェアカタログ、TechDocs、テンプレートの動作を短時間で体験できるため、最初の学習には最適です。

初期段階では「まず触って理解すること」が重要です。プラグイン追加やテーマ変更などもローカルで試しておくと、導入後の期待値ギャップを減らせます。

TechDocsを導入する場合は、リポジトリに/docsディレクトリとmkdocs.ymlを配置し、エンティティに backstage.io/techdocs-ref を追加します。CIでビルドした成果物をオブジェクトストレージに置き、Backstage側は読み取り専用にするとスケールしやすい構成になります。

PoC：代表的な社内サービスを登録し、Kubernetes連携まで試す

次に進めるのはPoC（概念実証）です。ここでは、社内の代表的なサービス（例：BFF／バッチ処理／フロントエンドなど）を3種類ほど選び、それぞれにcatalog-info.yamlを配置して登録します。そのうえで、TechDocs化率やテンプレート利用数といったKPIを設定すると効果が測りやすくなります。

さらにKubernetesプラグイン（フロント／バックエンド）を追加し、サービス画面からPodやイベントへ直接辿れるようにすると、運用上の価値が実感できます。PoC段階では「見える化」と「最低限の運用導線」の確立を優先し、細かい統合は本番移行後に進めるのが現実的です。

本番：永続DB・SSO・権限・バックエンド分離を整える

本番環境では、SQLiteからPostgreSQLなどの永続DBに切り替え、社内SSO（OIDC/SAML）と接続します。権限管理はPermission Frameworkを基盤にしつつ、RBACプラグインを利用することで、UI上で役割ごとに可視範囲や操作権限を細かく制御できます。

段階的な導入が原則であり、最初は「閲覧は広く、更新はチームごとに制御する」というポリシーから始めるのが定着しやすい方法です。バックエンドの分離や認証連携を進めても、ポータルの拡張性と一貫性を保つことが可能です。

出典：Backstage公式「Getting Started（ローカル起動と注意点）」
出典：Backstage公式「TechDocs／How-toガイド」
出典：Backstage公式「Kubernetes（構成・インストール）
出典：Backstage公式「Permission Framework 概要」
出典：Spotify Plugins「RBAC」

カタログ設計（エンティティ・関係・所有を“最初に決める”）

エンティティの型（Kind）と必須項目：標準4種から始める

Backstageのカタログは、Component／API／Resource／System／Domain／Group／Userといった複数のエンティティで構成されます。各リポジトリにはcatalog-info.yamlを置き、Descriptor Formatに従ってmetadata.name、spec.owner、spec.typeといった基本情報を正しく記載します。

実務でいきなり全種類を使おうとすると運用が複雑になるため、最初は Component・API・System・Groupの4種類に絞る のがおすすめです。これにより「どのチームがどのシステムを持っているか」をシンプルに把握でき、運用習慣が根付きやすくなります。

また、metadata.tagsを利用して「技術スタック（例：lang:java、runtime:node）」や「業務領域（例：domain:billing）」を記録しておくと、後から横断検索や棚卸しが容易になります。ただし、最初からタグを増やしすぎると管理が煩雑になるので、四半期ごとに見直すくらいのペースで整備するのが現実的です。

リレーション設計：Systemを“束ね”、Ownerを“責任点”に

Backstageの魅力の一つは、エンティティ間の関係（Relations）を定義できる点です。例えば：

• partOf：ComponentをSystemにまとめる

• consumesApi／providesApi：サービスが利用するAPIと提供するAPIを明示する

• ownerOf：どのチームがどのエンティティを所有しているかを可視化する

このようにSystemをハブに据え、Group（チーム）をspec.ownerとして登録することで、「どのチームがどのサービス群を管理しているのか」が明確になります。結果として、障害対応や担当移管の際に全体像を素早く把握できるようになります。

実務では、システムの境界が曖昧なケースも多いため、まずは最小限の関係だけ定義し、運用を通じて少しずつ拡張していくのが定着のコツです。依存関係のグラフが可視化されるだけでも、現場での価値は大きく向上します。

登録運用：未登録リポジトリの洗い出しと“型”の仕込み

Backstageを導入しても、catalog-info.yamlが付与されていないリポジトリが残ってしまうと、効果は大幅に薄れます。そのため導入初期は、スキャンを実行して未登録リポジトリを洗い出すことが大切です。

さらに新規リポジトリをテンプレートから作成した際に、catalog-info.yamlやTechDocsの雛形が自動で挿入されるように“型”を作っておくと、登録漏れを防げます。必須項目（name／owner／type／system）はテンプレート入力時に必ず入力させ、レビューやCIで重複名・欠落を検出する仕組みを入れると、品質を安定させられます。

出典：Backstage公式「Descriptor Format（エンティティ仕様）」
出典：Backstage公式「Catalog Configuration
出典：Backstage公式「System Model（関係の設計）」
出典：Roadie Blog「Understanding the Backstage System Model」
出典：Roadie Blog「Modelling Software in Backstage」

テンプレート（Scaffolder）とGolden Path：標準を“作って配る”

Scaffolderの基本：YAMLで“雛形＋アクション”を定義

BackstageのSoftware Templates（Scaffolder）は、YAMLで「入力（parameters）」と「処理ステップ（actions）」を定義する仕組みです。これにより、新しいリポジトリの作成、CI設定、初期コードの配置、カタログ登録までを自動化できます。

まずは「APIサーバ／フロントエンド／バッチ処理」の3種類をテンプレート化し、誰が作っても同じ初期状態になるようにしておくと、標準化の効果がすぐに出ます。テンプレート自体もカタログに登録し、利用状況をトラッキングすると改善サイクルが回しやすくなります。

入力項目は必要最小限に抑えるのがポイントです。命名やOwner、Systemといった必須項目だけを入力させ、自動的にPull Requestが生成されるようにすると、レビューでルール逸脱を防げます。テンプレートの更新は定期的（月次程度）に告知し、変更内容をTechDocsに残すと組織全体で再現性が高まります。

Golden Pathの考え方：迷わない“正しい作り方の道”を用意

Golden Pathとは「推奨される最短経路」のことを指します。具体的には、必要なテンプレート、CI/CDの初期設定、Kubernetesマニフェスト、監視設定を一式に揃え、「必須項目を入力するだけで正しい初期状態が手に入る」流れを提供することです。

最初から多くのGolden Pathを用意する必要はありません。まずは1経路（例：Web API on Kubernetes）をしっかり整備し、実際の利用実績を見ながら拡張していくのが現実的です。Spotifyのオンボーディング記事でも、この段階的アプローチが推奨されています。

Golden Pathは「禁止事項を列挙する運用ルール」ではなく、「推奨と自動化で迷いを減らす仕組み」として機能させるのが重要です。例外対応はチケットで吸収するなど、スピードとガバナンスを両立させる運用を心がけましょう。テンプレートの成否は「どれだけ繰り返し利用されるか」で測り、利用率をKPIとして追うと効果を定量的に把握できます。

事例と雛形リポジトリ：既存テンプレを参考に“内製化”

Backstage公式やコミュニティが提供しているテンプレートや雛形リポジトリは、導入初期に非常に有効です。これらを利用すれば、GitHub ActionsやArgo CDといった実践的なCI/CDまで含まれた「動く型」を最短で得られます。

PoCの段階で経営層やステークホルダーに納得してもらう材料としても使えるため、まずは既存のテンプレートを徹底的に読み込み、命名規則やパラメータ設計の良い部分を取り込んで社内標準へとアレンジしていきましょう。

出典：Backstage公式「Software Templates」
出典：Backstage公式「Writing Templates」
出典：Spotify「Backstage 101（Golden Pathの考え方）」

運用・拡張（TechDocs／権限／Kubernetes／運用KPI）

TechDocs（docs-like-code）を“カタログの隣に”置く

TechDocsは、MarkdownとMkDocsをベースにドキュメントを自動生成し、Backstage上で閲覧できる仕組みです。各リポジトリに/docsディレクトリとmkdocs.ymlを標準配置し、CIでビルドした成果物をオブジェクトストレージに配置します。Backstageは“読み取り専用”として扱う構成にすると、運用がシンプルでスケールしやすくなります。

この仕組みにより、RunbookやAPI仕様書などが「コードと同じ場所で管理される」ため、情報の陳腐化を防ぎやすくなります。特に更新頻度の高い手順書や設定ガイドから取り込むと、効果を実感しやすいです。

また、mkdocs-techdocs-coreなどのプラグインが提供されているため、標準的なフォーマットで始めやすい点もメリットです。ただし、社内の書式を細かく強制すると更新されなくなるため、最低限の章立てだけを決め、表紙や注意書きはテンプレートで配布する程度が現実的です。

権限管理：Permission Framework＋RBACで“見せ方”を制御

Backstageの権限管理は、Permission Frameworkを中心に設計されています。各プラグインは中央のポリシー決定を参照するため、一貫性を保ちながら認可を制御できます。

さらに、UIベースで操作できるRBACプラグインを利用すると、ユーザーやグループをロールに紐づけ、可視範囲や操作権限を細かく切り分けることが可能です。初期段階では「閲覧は全社、更新はチーム単位」といったシンプルなルールから導入し、例外はロール追加で対応すると定着しやすいです。

また、監査観点では「誰が何を更新したのか」を追えるように、GitやCIの履歴と紐づけておくと安心です。権限を最初から細かく定義しすぎると負担が大きいため、利用が広がるにつれてロールを見直す程度がちょうど良い運用スタイルです。

可観測性とKubernetes連携：ポータルから“運用の入口”を一本化

BackstageにKubernetesプラグインを導入すると、サービスの画面からDeploymentsやPods、イベント情報に直接アクセスできます。これにより、開発者はクラスタ管理ツールを行き来することなく、Backstageを「運用の入り口」として使えるようになります。特にオンボーディング時や当番対応時に大きな効果を発揮します。

さらに、監視・アラート・エラートラッキングツール（例：Grafana、Alertmanager、Sentry）へのディープリンクをポータルに集約すれば、徐々に運用情報をBackstageに集めていくことが可能です。最初はリンク集約から始め、慣れてきたらメトリクスのサマリー表示まで拡張すると、段階的に導入できます。

運用KPIとしては、「カタログ登録率」「TechDocs化率」「テンプレート利用率」を月次で追うと、定着度や投資対効果を可視化しやすくなります。

出典：Backstage公式「TechDocs（概要／How-to）」
出典：GitHub「mkdocs-techdocs-core」
出典：Backstage公式「Permissions Overview」
出典：Spotify公式「RBAC Plugin／Core Concepts」
出典：Backstage公式「Kubernetes（概要と構成）」

まとめ：内製PaaS（Backstage）は“カタログ設計×テンプレ”で成果を早出し

Backstageを活用するうえでの第一歩は、ソフトウェアカタログを整備し「何がどこにあるのか」を明確にすることです。これにより、組織内の情報が統一され、オンボーディングが一気に効率化されます。続いてTechDocsを導入し、「知識をコードの隣に置く」体制を作ることで、ドキュメントの陳腐化を防ぎながら活用を進められます。

さらにテンプレート（Scaffolder）を使って「正しい作り方を配布」すれば、誰でも同じ品質でサービスを立ち上げられるようになり、Golden Pathによる標準化が組織に根付いていきます。

導入の進め方としては、以下のように段階を追うのが効果的です。

1. ローカル環境でBackstageを試し、動作や特徴を体感する

2. PoCで代表的な3サービスを登録し、Kubernetes連携まで実施する

3. 本番では認証・権限管理・永続DBを導入し、拡張性を確保する

また、カタログ設計ではエンティティ・関係・所有を最初に決めておくことが安定運用への近道です。さらに、Kubernetesや監視との統合によって、Backstageを「開発から運用までのハブ」として活用できます。

運用KPI（登録率・TechDocs化率・テンプレ利用率）を定期的に追いながら、CNCF配下で成熟を続けるBackstageのエコシステムを拠り所にすることで、短期間で“使える内製PaaS”を形にできます。