Backstageを使った内部開発者プラットフォーム（IDP）構築入門【2025年版】

はじめに：Platform EngineeringとIDP、Backstageの役割

開発チームの増加やマイクロサービスの複雑化に伴い、「開発者の認知負荷」が生産性を下げる大きな要因となっています。Platform Engineeringは、この課題を解決するためのアプローチです。クラウドネイティブ技術を使い、開発に必要なツール、インフラ、ワークフローを一つの「プラットフォーム」として提供することで、開発者がアプリケーション開発そのものに集中できる環境を目指します。

そのプラットフォームへの統一されたエントリーポイントが、内部開発者プラットフォーム（Internal Developer Platform, IDP）です。そして、IDPを構築するためのオープンソースプロジェクトとしてデファクトスタンダードとなっているのが、Spotifyによって開発され、現在CNCFのIncubatingプロジェクトであるBackstageです。

Backstageが提供する主な機能:

• Software Catalog: 組織内のすべてのソフトウェア（サービス、ライブラリ、Webサイトなど）を一覧化し、所有者や依存関係を可視化します。
• Software Templates: ベストプラクティスが組み込まれた新しいサービスやコンポーネントを数分で作成できます。
• TechDocs: ドキュメントをコードと同じリポジトリで管理し、Backstage上で美しく表示します。
• 豊富なプラグインエコシステム: CI/CD、モニタリング、セキュリティスキャンなど、既存のツールと簡単に連携できます。

本記事では、Backstageをローカル環境でセットアップし、IDPとしての基本的な機能であるSoftware CatalogとSoftware Templates、TechDocsを体験するまでの手順を解説します。

ステップ1：開発環境の準備とBackstageアプリの作成

Backstageアプリを作成するには、Node.js, npx, yarn, そしてDockerが必要です。

1. 前提ツールのインストール: Node.js (v18+), yarn (v1+) がインストールされていることを確認してください。
2. Backstageアプリの作成: npxを使って、インタラクティブにBackstageアプリを作成します。

# npx @backstage/create-app@latest
? Enter a name for the app [required]
> my-backstage-app

このコマンドを実行すると、my-backstage-appというディレクトリが作成され、フロントエンドとバックエンドを含むBackstageアプリの雛形が生成されます。処理には数分かかります。

ステップ2：Backstageの起動と基本画面の確認

作成されたディレクトリに移動し、yarn devコマンドで開発サーバーを起動します。

cd my-backstage-app
yarn dev

このコマンドは、フロントエンド（デフォルト: ポート3000）とバックエンド（デフォルト: ポート7007）の両方を起動します。

起動が完了したら、ブラウザで http://localhost:3000 にアクセスします。Backstageのウェルカムページが表示されれば成功です。

左側のメニューから以下の主要な機能を確認できます。

• Catalog: 登録されているコンポーネント、API、リソースなどが表示されます。
• Docs: TechDocsで管理されているドキュメントが表示されます。
• Create...: Software Templatesを使って新しいコンポーネントを作成する開始点です。

ステップ3：ソフトウェアテンプレートのカスタマイズと利用

Backstageの最も強力な機能の一つが、新しいサービスを定型化された手順で作成できるSoftware Templatesです。ここでは、既存のテンプレートを少し変更し、実際に使ってみましょう。

テンプレート定義ファイルの確認

テンプレートの定義は、app-config.yamlで指定された場所にあります。デフォルトでは、./templatesディレクトリにサンプルが含まれています。

templates/template-react-ssr-app/template.yaml を見てみましょう。このファイルには、テンプレートがユーザーに尋ねるパラメータ（parameters）と、それらのパラメータを使って実行されるアクション（steps）が定義されています。

テンプレートからコンポーネントを作成する

1. 左メニューの「Create...」をクリックします。
2. 「React SSR App Template」を選択します。
3. フォームに必要な情報を入力します。例えば、コンポーネント名として my-first-component、所有者として default/guest を指定します。
4. 「Next Step」をクリックし、内容を確認後、「Create」をクリックします。

Backstageはバックグラウンドで以下の処理を実行します。

• template.yamlのstepsに従い、テンプレートのスケルトンをフェッチします。
• パラメータを元にファイルの内容を書き換えます。
• 指定されたGitHubリポジトリに新しいコードをプッシュし、リポジトリをBackstageのCatalogに登録します。

処理が完了すると、新しいコンポーネントのCatalogページにリダイレクトされます。所有者、依存関係、利用可能なドキュメントなどが一目でわかります。

ステップ4：TechDocsによるドキュメント管理

TechDocsは、「Docs like Code」を実現する機能です。Markdownで書かれたドキュメントを、コンポーネントのソースコードと一緒にGitリポジトリで管理します。

ドキュメントの準備

先ほど作成したmy-first-componentのリポジトリに、ドキュメントを追加してみましょう。

1. リポジトリのルートにmkdocs.ymlというファイルを作成します。これはドキュメントサイトの設定ファイルです。

   site_name: 'My First Component'

2. docsディレクトリを作成し、その中にindex.mdを配置します。

   # My First Component
   
   This is the documentation for my first component created with Backstage.

Catalogへの登録

コンポーネントの情報を定義するcatalog-info.yaml（リポジトリのルートにあります）を編集し、ドキュメントの場所をBackstageに教えます。

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: my-first-component
  # ... 他のメタデータ
  annotations:
    # このアノテーションを追加
    backstage.io/techdocs-ref: dir:.
spec:
  type: service
  lifecycle: experimental
  owner: default/guest

• backstage.io/techdocs-ref: dir:.: このアノテーションは、「TechDocsのソースは、このcatalog-info.yamlファイルと同じディレクトリ（.）にあります」という意味です。

これらの変更をGitHubにプッシュします。

ドキュメントの表示

BackstageのCatalogページに戻り、my-first-componentのページを更新します。しばらくすると「DOCS」タブが表示され、クリックすると先ほど作成したMarkdownファイルがレンダリングされたドキュメントとして表示されます。

まとめ：IDPによる開発者体験の向上

本記事では、Backstageを使って内部開発者プラットフォーム（IDP）を構築する最初の一歩を解説しました。

• npx @backstage/create-app で簡単にアプリケーションを作成できる。
• Software Catalogで組織のソフトウェア資産を一元管理できる。
• Software Templatesでベストプラクティスに基づいた開発を標準化できる。
• TechDocsでドキュメントをコードと共に管理し、常に最新の状態を保てる。

Backstageの真価は、その強力なプラグインエコシステムにあります。CI/CDの実行結果、コードカバレッジ、セキュリティスキャン結果、本番環境のモニタリング情報など、開発者が必要とするあらゆる情報をBackstageのコンポーネントページに集約することで、開発者の認知負荷を劇的に下げ、生産性を向上させることができます。

まずは今回紹介した基本機能から始め、自社の開発ワークフローに合わせてプラグインを導入し、IDPを育てていくことが成功への鍵となります。