--- title: 入門Backstage _ System Modelの理解と活用方法 tags: author: [Naoto Koizumi](https://www.docswell.com/user/koizumi_naoto) site: [Docswell](https://www.docswell.com/) thumbnail: https://bcdn.docswell.com/page/GJ5GRGK5J4.jpg?width=480 description: 入門Backstage _ System Modelの理解と活用方法 by Naoto Koizumi published: March 22, 24 canonical: https://www.docswell.com/s/koizumi_naoto/K7V2M7-pfem-online-1 --- # Page. 1 ![Page Image](https://bcdn.docswell.com/page/GJ5GRGK5J4.jpg) Platform Engineering Meetup Online #1 入門Backstage System Modelの理解と活用方法 Naoto Koizumi , Gunosy Inc. # Page. 2 ![Page Image](https://bcdn.docswell.com/page/9E2YDYWGER.jpg) Platform Engineering Meetup Online #1 目次 ● イントロダクション ● Software Catalogについて ● System Modelについて ● System Modelの各エンティティとそのフォーマットについて ● 課題と解決事例の紹介 ● まとめ # Page. 3 ![Page Image](https://bcdn.docswell.com/page/D7YG2GLG7M.jpg) Platform Engineering Meetup Online #1 エレベーターピッチ 【Platform Engineeringに興味がある人】 、 【Backstage/Internal Developer Portalに興味がある人】 向けに発表する 【入門Backstage：System Modelの理解と活用方法】 は 【Backstageの中心機能である Software Catalogを設定する上で重要な System Modelの概 念を理解し、活用できるようにするための発表】 です # Page. 4 ![Page Image](https://bcdn.docswell.com/page/VENG8G48J8.jpg) Platform Engineering Meetup Online #1 終了後に狙う状態 ● 論理面 ○ Software Catalogを作成する上で重要な System Modelの概念がﾁｮｯﾄﾜｶﾙ ○ Software Catalogについてﾁｮｯﾄﾜｶﾙ ● 感情面 ○ Backstageにより興味を持って、やってみたいと思える # Page. 5 ![Page Image](https://bcdn.docswell.com/page/Y79WKWQX73.jpg) Platform Engineering Meetup Online #1 自己紹介 氏名：小泉 直人（ X : @koizum_ ） 経歴： - 富士通（2020/04~） - Gunosy（2022/01~） 業務：SRE - SLI／SLO周りやセキュリティに関する部分を主に担当 趣味：音楽、映画、 MLB（トロント・ブルージェイズ） # Page. 6 ![Page Image](https://bcdn.docswell.com/page/G78NRNG9JD.jpg) Platform Engineering Meetup Online #1 Software Catalogについて # Page. 7 ![Page Image](https://bcdn.docswell.com/page/L7LPKPGMJR.jpg) Software Catalogについて はじめに こんなことありませんか？ ● ● ● ● 特定のリポジトリ、クラウドリソースにおいて、どのチームがオーナーシップを持ってい るかわからず、問い合わせ先がわからない オーナーが不明瞭で、リポジトリが長らくメンテナンスされていない どのリポジトリでどのクラウドリソースを管理しているかがわかりづらい どのリポジトリが依存関係にあるのかがわからない こんな問題を改善してくれるのが Backstageのソフトウェアカタログ # Page. 8 ![Page Image](https://bcdn.docswell.com/page/4EM424Q6JW.jpg) Software Catalogについて Software Catalogとは 各リポジトリのソフトウェアや各クラウドサービスのリソースに関する所有権とメタデータを集 約し、Backstageのポータルに可視化する機能 具体的には、該当のリポジトリやクラウドリソースがどのチームの所有物なのか、どのリポジ トリ、リソースに依存しているかを確認することができます 動線の集約が可能になり、検索容易性を上げ、エンジニアの認知負荷の低減を行うことがで きる # Page. 9 ![Page Image](https://bcdn.docswell.com/page/PERWMW8NJ9.jpg) Software Catalogについて Software Catalogとは Portal画面からソフトウェアの Owner、依存関係などが一目で 見てわかる https://demo.backstage.io/ # Page. 10 ![Page Image](https://bcdn.docswell.com/page/P7XPVP88JX.jpg) Software Catalogについて Software Catalogのユースケース ● ● ● マイクロサービスアーキテクチャを採用している組織に特に有効 ○ リポジトリが分散している状態のなかで、その情報を Backstageに集約し、それ ぞれのOwner、依存関係を可視化するのに役立つ ○ 開発者はサービスに関する情報を 1つの場所で確認できる 複数のチームが存在し、それぞれが独立して開発を行っている組織に有効 ○ 技術スタックや開発手法が異なる場合、システムのメタデータを Backstageに集 約することで一元的に管理・確認することができる 新入社員のオンボーディングにも使える # Page. 11 ![Page Image](https://bcdn.docswell.com/page/37KDQDKLED.jpg) Software Catalogについて catalog-info.yaml カタログに含める各コンポーネントやサービ ス、APIなどのエンティティを指定し、それらの メタデータや関連情報を定義します リポジトリのトップレベルに右記のような catalog-info.yaml を置くことで、該当のリポジ トリの依存関係や所有権が Backstage上で可 視化される apiVersion: backstage.io/v1alpha1 kind: Component metadata: name: backstage description: | Backstage is an open-source developer portal that puts the developer experience first. links: - title: Website url: http://backstage.io - title: Documentation url: https://backstage.io/docs - title: Storybook url: https://backstage.io/storybook - title: Discord Chat url: https://discord.com/invite/EBHEGzX annotations: github.com/project-slug: backstage/backstage backstage.io/techdocs-ref: dir:. lighthouse.com/website-url: https://backstage.io spec: type: library owner: CNCF lifecycle: experimental # Page. 12 ![Page Image](https://bcdn.docswell.com/page/LJ3RPRZ6E5.jpg) Software Catalogについて エンティティとは Backstageにおけるエンティティは、ソフトウェア開発に関連する様々な要素や情報を表しま す。Backstageのエンティティは、特定のソフトウェアやサービス、 API、インフラリソースなどを 指します。 エンティティは System ModelというBackstageの概念に基づいて分類されており、各エンティ ティを用いて、複数のソフトウェアやサービス、 API、インフラリソースの依存関係や所有権を 表現します。 # Page. 13 ![Page Image](https://bcdn.docswell.com/page/8JDYLYRMJG.jpg) Platform Engineering Meetup Online #1 System Modelについて # Page. 14 ![Page Image](https://bcdn.docswell.com/page/VEP626WQ78.jpg) System Modelについて System Modelとは Backstage上でシステムコンポーネントの依存関係や所有権を表現するための概念で、以下 のようなエンティティを用いてシステムをモデル化します （引用元: Backstage - System Model） # Page. 15 ![Page Image](https://bcdn.docswell.com/page/27V3D38PJQ.jpg) System Modelについて System Modelとは 右図のような関係で、以下のエンティティの 種類があります ● ● ● ● ● ● ● Component API Resource System Domain Group/User Location # Page. 16 ![Page Image](https://bcdn.docswell.com/page/5JG3Y35QEL.jpg) Platform Engineering Meetup Online #1 各エンティティとそのフォーマットについて # Page. 17 ![Page Image](https://bcdn.docswell.com/page/47Q5M5ZWEP.jpg) # Page. 18 ![Page Image](https://bcdn.docswell.com/page/KE49V931J1.jpg) 各エンティティとそのフォーマットについて Kind: Component Componentはソフトウェアそのものを指します。（ e.g. バックエンドサービスなど） 基本的に特定の GitHubリポジトリと1対1対応させます。また、 Componentは SubComponentを持つことができるので、モノレポ構成の場合には、 SubComponentを使っ て表現することができます。 apiVersion: backstage.io/v1alpha1 kind: Component metadata: name: <repository_name> annotations: github.com/project-slug: hoge/<repository_name> spec: type: service ## ソフトウェアの種類 owner: team-a subcomponentOf: <repository_name> # Page. 19 ![Page Image](https://bcdn.docswell.com/page/L71K3K15EG.jpg) # Page. 20 ![Page Image](https://bcdn.docswell.com/page/G7WDPD8WE2.jpg) 各エンティティとそのフォーマットについて Kind: API Component間の境界を表現するエンティティ。 ComponentがOpenAPI, AsyncAPI, GraphQL, gRPC などのAPIを提供する場合、または依存する場合、その Interfaceを定義しま す。 apiVersion: backstage.io/v1alpha1 kind: API metadata: name: <api_name> spec: type: openapi ## 使用するAPIフォーマット owner: team-a apiConsumeBy: - <component_name> ## このAPIを使用しているComponentを定義 apiProvidedBy: - <component_name> ## このAPIを提供しているComponentを定義 definition: | openapi: “3.0.0” … # Page. 21 ![Page Image](https://bcdn.docswell.com/page/4JZGKG8273.jpg) 各エンティティとそのフォーマットについて Kind: API すでにリポジトリに swagger.jsonなどを配置している場合は、 spec.definitionを下記のように 定義することで、 Interface定義をUIで確認することができます。 apiVersion: backstage.io/v1alpha1 kind: API metadata: name: <api_name> spec: type: openapi owner: team-a definition: $text: https://github.com/hoge/<repository_name>/blob/<default_branch_name>/swagger/swagger.json … # Page. 22 ![Page Image](https://bcdn.docswell.com/page/YE6YQYK6JV.jpg) # Page. 23 ![Page Image](https://bcdn.docswell.com/page/GE5GRGP5E4.jpg) 各エンティティとそのフォーマットについて Kind: Resource Component（ソフトウェア）が動作するために必要なインフラリソース（コンピュートリソース、 データベース、ストレージなど）を指します。 各インフラリソースと１対１対応させます。環境が複数ある場合には、全環境分を定義する必 要があります。異なる複数の AWSアカウントなどに同名のリソースが存在する可能性がある ため、metadata.namespaceを追加することで衝突を回避します。 apiVersion: backstage.io/v1alpha1 kind: Resource metadata: namespace: <namespace_name> name: <resource_name> spec: type: aws_s3_bucket … # Page. 24 ![Page Image](https://bcdn.docswell.com/page/972YDY6G7R.jpg) 各エンティティとそのフォーマットについて Kind: Resource 定義したResourceは、Componentのspec.dependsOnで指定することで、関係性を定義する ことができます apiVersion: backstage.io/v1alpha1 kind: Resource metadata: namespace: <namespace_name> name: <resource_name> spec: type: aws_s3_bucket … apiVersion: backstage.io/v1alpha1 kind: Component metadata: name: <repository_name> annotations: github.com/project-slug: hoge/<repository_name> spec: type: service owner: team-a dependsOn: - resource:<namespace_name>/<resource_name> # Page. 25 ![Page Image](https://bcdn.docswell.com/page/DJYG2G9GJM.jpg) # Page. 26 ![Page Image](https://bcdn.docswell.com/page/V7NG8GL8E8.jpg) 各エンティティとそのフォーマットについて Kind: System ソフトウェアやサービスを統合して構成するシステム全体を表し、これまで紹介した Component, API, Resourceの集合体をSystemとして定義します。 定義の粒度については、必ずしも Componentに合わせる必要はありませんが、何らか認識 しやすい粒度に分解しておくと理解しやすいです。 apiVersion: backstage.io/v1alpha1 kind: System metadata: namespace: <namespace_name> name: <system_name> spec: … # Page. 27 ![Page Image](https://bcdn.docswell.com/page/YJ9WKW4XJ3.jpg) 各エンティティとそのフォーマットについて Kind: System 定義したSystemをComponentなどのエンティティ定義の spec.systemで指定することで、 Componentなどが所属する Systemを定義することができます apiVersion: backstage.io/v1alpha1 kind: Component metadata: name: <repository_name> annotations: github.com/project-slug: hoge/<repository_name> spec: type: service owner: team-a system: <system_name> dependsOn: - resource:<namespace_name>/<resource_name> # Page. 28 ![Page Image](https://bcdn.docswell.com/page/GJ8NRNQ9ED.jpg) # Page. 29 ![Page Image](https://bcdn.docswell.com/page/LJLPKPXMER.jpg) 各エンティティとそのフォーマットについて Kind: Domain Systemが取り扱うビジネスドメインを指します。 System側のspec.domainで関係性を定義することができます。 組織やシステムの規模によっては、 Systemで一定充足する場合もあります。 （現状、弊社では Domainは定義していません） apiVersion: backstage.io/v1alpha1 kind: Domain metadata: name: <domain_name> spec: owner: team-a apiVersion: backstage.io/v1alpha1 kind: System metadata: namespace: <namespace_name> name: <system_name> spec: owner: team-a domain: <domain_name> ## 取り扱うDomainを指定 # Page. 30 ![Page Image](https://bcdn.docswell.com/page/47M424L6EW.jpg) # Page. 31 ![Page Image](https://bcdn.docswell.com/page/P7RWMWKNE9.jpg) 各エンティティとそのフォーマットについて Kind: User/Group 開発チームを Groupとして、そのチームに所属するメンバーを Userとして表現することができ ます Component, API, Resourceなどのエンティティには Owner の定義が必須になっているので、 必ず該当する Groupを定義するようにしましょう apiVersion: backstage.io/v1alpha1 kind: Group metadata: name: team-a description: Team A spec: type: team profile: email: team-a@example.com parent: team-admin ## 親組織がある場合に定義 children: [] apiVersion: backstage.io/v1alpha1 kind: User metadata: name: breanna.davison spec: profile: email: breanna-davison@example.com memberOf: [team-a, team-b] # Page. 32 ![Page Image](https://bcdn.docswell.com/page/PJXPVPL8EX.jpg) 各エンティティとそのフォーマットについて ここで一旦Break リポジトリのトップレベルに、これまで紹介したエンティティを定義した catalog-info.yamlを配 置することで、 Backstageにエンティティを登録できます ただ、catalog-info.yamlが巨大になってしまい、可読性が著しく低下してしまう可能性があり ます # Page. 33 ![Page Image](https://bcdn.docswell.com/page/3JKDQDLL7D.jpg) 各エンティティとそのフォーマットについて ディレクトリ構成 以下のように、それぞれのエンティティでディレクトリを分けて記述し、ルートディレクトリの catalog-info.yamlに各定義ファイルを集約することができます。 . |ー catalog-info.yaml ## 各定義ファイルを集約 |ー domains | └── hoge-domain.yaml ## ドメイン |ー systems | └── hoge-system.yaml ## システム |ー group | └── team-a.yaml ## 開発チーム A | └── team-b.yaml ## 開発チーム B |ー users └── michael.yaml ## チームメンバー # Page. 34 ![Page Image](https://bcdn.docswell.com/page/LE3RPR3675.jpg) 各エンティティとそのフォーマットについて Kind: Location 複数のカタログファイルを集約する場合に Locationエンティティを使用します # catalog-info.yaml apiVersion: backstage.io/v1alpha1 kind: Location metadata: name: <location_name> spec: type: url targets: # Domain - https://github.com/koizumi/backstage/blob/main/domains/hoge-domain.yaml # System - https://github.com/koizumi/backstage/blob/main/systems/hoge-system.yaml # Group - https://github.com/koizumi/backstage/blob/main/groups/team-a.yaml - https://github.com/koizumi/backstage/blob/main/groups/team-b.yaml # User - https://github.com/koizumi/backstage/blob/main/users/michael.yaml # Page. 35 ![Page Image](https://bcdn.docswell.com/page/8EDYLY4MEG.jpg) Platform Engineering Meetup Online #1 課題と解決事例の紹介 # Page. 36 ![Page Image](https://bcdn.docswell.com/page/V7P626MQJ8.jpg) おさらい 課題と解決事例の紹介 Kind: Resource Component（ソフトウェア）が動作するために必要なインフラリソース（コンピュートリソース、 データベース、ストレージなど）を指します。 各インフラリソースと１対１対応させます。 環境が複数ある場合には、全環境分を定義する必 要があります 。異なる複数の AWSアカウントなどに同名のリソースが存在する可能性がある ため、metadata.namespaceを追加することで衝突を回避します。 apiVersion: backstage.io/v1alpha1 kind: Resource metadata: namespace: <namespace_name> name: <resource_name> spec: type: aws_s3_bucket … 全てのResourceを手動 で定義するのは中々に 骨が折れる作業 # Page. 37 ![Page Image](https://bcdn.docswell.com/page/2JV3D39PEQ.jpg) 課題と解決事例の紹介 Resourceエンティティの自動登録 Terraformで管理しているリソースを、 tfstate.jsonのデータから Resource Catalog （catalog-info.yaml）を自動生成するツールを作成しています tfstate.json convert.py catalog-info.yaml # Page. 38 ![Page Image](https://bcdn.docswell.com/page/5EG3Y3ZQ7L.jpg) 課題と解決事例の紹介 [参考] convert.pyについて 以下のように、引数として指定することで、 tfstate.jsonで定義されている Terraformリソース を、BackstageのResource Catalogに変換し、catalog-info.yamlに出力することができます python ./convert.py \ --namespace ${{ namespace_name }} \ --input ./tfstate.json \ --output ./catalog-info.yaml # Page. 39 ![Page Image](https://bcdn.docswell.com/page/4JQ5M5LW7P.jpg) 課題と解決事例の紹介 生成結果例 tfstate.jsonの内容から以下のように catalog-info.yamlが生成されます （以下は自動生成された ECS ClusterのResource Catalogの例） 'apiVersion': 'backstage.io/v1beta1' 'kind': 'Resource' 'metadata': 'annotations': 'amazonaws.com/account-id': <accoun_id> 'amazonaws.com/arn': 'arn:aws:ecs:ap-northeast-1:<accoun_id>:cluster/<cluster_name>' 'amazonaws.com/region': 'ap-northeast-1' 'name': 'aws-ecs-cluster-hoge' 'namespace': 'sandbox' 'spec': 'lifecycle': 'production' 'owner': 'default/team-sre-reviewers' 'system': 'sandbox/default' 'type': 'aws_ecs_cluster' # Page. 40 ![Page Image](https://bcdn.docswell.com/page/K749V9D1E1.jpg) 課題と解決事例の紹介 Resourceエンティティの自動登録 さらに、そのツールを Github Actionsのワークフロー内で使えるように Composite Actions化 しています tfファイルを管理している各リポジトリの CIの中で、以下のように記述することで、 terraform state pull でtfstate.jsonを取得し、その内容をもとに catalog-info.yamlを自動生成してくれま す - uses: hoge/backstage/actions/terraform-to-backstage-catalog@main with: namespace: <namespace_name> # Page. 41 ![Page Image](https://bcdn.docswell.com/page/LJ1K3KZ57G.jpg) 課題と解決事例の紹介 Resourceエンティティの自動登録 自動生成した catalog-info.yamlは、共通のAWSアカウントのS3にリポジトリ単位のディレクト リに、tfstateの管理単位ごとにアップロードされ、 Backstageの AWS S3 Integration を用い てエンティティの自動登録を行っています <s3_bucket_name>/<repository_name> |ー dev | └── catalog-info.yaml |ー stg | └── catalog-info.yaml |ー prd : └── catalog-info.yaml # Page. 42 ![Page Image](https://bcdn.docswell.com/page/GJWDPD9W72.jpg) 課題と解決事例の紹介 AWS S3 Integration S3バケットにあるカタログファイルを検出するための Integration 複数のカタログファイルを含むバケットをクロールし、ファイル内で定義されたエンティティを 自動でBackstageに登録してくれます # app-config.yaml（Backstageの設定ファイル） catalog: providers: awsS3: yourProviderId: # identifies your dataset / provider independent of config changes bucketName: <bucket_name> ## catalog-info.yamlがあるS3バケット名 prefix: prefix/ # optional region: ap-northeast-1 schedule: # same options as in TaskScheduleDefinition # supports cron, ISO duration, "human duration" as used in code frequency: { minutes: 30 } # supports ISO duration, "human duration" as used in code timeout: { minutes: 3 } # Page. 43 ![Page Image](https://bcdn.docswell.com/page/4EZGKG92J3.jpg) 課題と解決事例の紹介 AWS S3 Integration 注意点として、デフォルトのプロバイダではないので、 AWSカタログのプラグインを別途イン ストールする必要があります yarnでパッケージをインストールし、 packages/backend/src/plugins/catalog.ts に以下を追記 します（詳細は公式ドキュメントに記載されています） /* packages/backend/src/plugins/catalog.ts */ import { AwsS3EntityProvider } from '@backstage/plugin-catalog-backend-module-aws'; const builder = await CatalogBuilder.create(env); /** ... other processors and/or providers ... */ builder.addEntityProvider( AwsS3EntityProvider.fromConfig(env.config, { logger: env.logger, scheduler: env.scheduler, }), ); # Page. 44 ![Page Image](https://bcdn.docswell.com/page/Y76YQYD6EV.jpg) Platform Engineering Meetup Online #1 まとめ # Page. 45 ![Page Image](https://bcdn.docswell.com/page/G75GRG3574.jpg) Platform Engineering Meetup Online #1 まとめ ● Software Catalogを定義する上で重要な System Modelの概念について紹介 ● 各エンティティについて、それぞれの YAML Formatについて紹介 ● カタログファイルを定義する上での課題の解決事例を紹介 ○ Terraformのtfstate.jsonからResource Catalogを自動生成 ○ AWS S3 Integrationを用いてS3のカタログファイルを Backstageへ登録 # Page. 46 ![Page Image](https://bcdn.docswell.com/page/9J2YDYZGJR.jpg) Platform Engineering Meetup Online #1 入門Backstage System Modelの理解と活用方法 Naoto Koizumi , Gunosy Inc.