🗺️

Backstageの基本およびSystem Modelについて

2024/01/13に公開

最近、Backstageについて自分でも調べて触ってみたりしていますが、Backstage Appがどういったファイル構成で、各ファイルがどのような用途で使われるのかを整理してみます。
その上で、Backstageの基本機能についてと、その機能を実装するために理解しておきたいSystem Modelと言われる概念を紹介します。

https://backstage.io/

ファイル構成

Backstageのアプリケーションを作成すると以下のようなファイル群が生成されます。

.
├── README.md
├── app-config.local.yaml
├── app-config.production.yaml
├── app-config.yaml
├── backstage.json
├── catalog-info.yaml
├── dist-types
│   ├── packages
│   └── tsconfig.tsbuildinfo
├── examples
│   ├── entities.yaml
│   ├── org.yaml
│   └── template
├── lerna.json
├── node_modules
├── package.json
├── packages
│   ├── README.md
│   ├── app
│   └── backend
├── playwright.config.ts
├── plugins
│   └── README.md
├── tsconfig.json
└── yarn.lock

この中でもBackstageの基本的な機能を実現するために重要な以下について、簡単に説明します。

./app-config.yaml
./catalog-info.yaml

app-config.yaml

Backstage Appの設定を記述するファイルになります。
app-config.local.yamlとapp-config.production.yamlでは、ローカル環境と本番環境のそれぞれにおいて、app-config.yamlを上書きしたい部分を記述します。
以下のように設定内容を記述します。

demoと同じように、app-config.yamlにローカル環境および両環境で共通する設定を、app-config.production.yamlに本番環境の設定を上書き部分のみ記述するのが良さそうですね。

細かい内容については長くなりそうなので、今回は割愛しますが、別記事で紹介できればなと思っています。

catalog-info.yaml

具体的な詳細は以下を参照してください。

ここでは、catalog-info.yamlを記述する上で重要な、System Modelの概念について紹介したいと思います。
公式ドキュメントに記載のある、以下の図で各要素がまとまっています。

その中でもコアエンティティと呼ばれる、Component/API/Resourceについて紹介します。

Component

Componentは、Webサイトやバックエンドサービスなどのようなソフトウェアのことを指します。
以下のように、metadataでGitHub Repositoryと1対1対応させます。
また、ComponentはSubComponentを持つことができるので、モノレポ構成の場合には、SubComponentとして表現しましょう。

API

Componentが公開するAPI（OpenAPI、AsyncAPI、GraphQL、gRPC）を指します。これにより、コンポーネントの境界を表現することができます。
以下のように記述した場合、https://demo.backstage.io/catalog/default/api/demo-graphql　のようにUIで出力されます。

Resource

Componentが動作するために必要なコンピュートリソース、データベース、ストレージなどのインフラサービスを指します。
以下のように記述しますが、環境が複数ある場合には、全環境分を定義する必要があります。また、異なるAWSアカウントに同名のリソースがある場合には、namespaceを定義することで衝突を回避することができます。

System

Component/API/ResourceをまとめたものをSystemとして定義することができます。Systemとしてまとめる粒度は、自分で決定できます。specに、後述するDomainを設定することができます。

Domain

Systemの上位概念としてDomainというものも存在します。Domainは、Systemをまとめてビジネスドメイン（プロダクト、サービス）として表現することができます。

おわりに

以上、Backstageの基本機能を実現するapp-config.yamlとcatalog-info.yamlについての簡単な紹介と、BackstageのSystem Modelの概念について紹介しました。
引き続きキャッチアップしていければと思うので、より詳細な内容について今後書ければと思います。