入門Backstage _ System Modelの理解と活用方法

Platform Engineering Meetup Online #1 入門Backstage System Modelの理解と活用方法 Naoto Koizumi , Gunosy Inc.

Platform Engineering Meetup Online #1 目次 ● イントロダクション ● Software Catalogについて ● System Modelについて ● System Modelの各エンティティとそのフォーマットについて ● 課題と解決事例の紹介 ● まとめ

Platform Engineering Meetup Online #1 エレベーターピッチ 【Platform Engineeringに興味がある人】 、 【Backstage/Internal Developer Portalに興味がある人】 向けに発表する 【入門Backstage：System Modelの理解と活用方法】 は 【Backstageの中心機能である Software Catalogを設定する上で重要な System Modelの概 念を理解し、活用できるようにするための発表】 です

Platform Engineering Meetup Online #1 終了後に狙う状態 ● 論理面 ○ Software Catalogを作成する上で重要な System Modelの概念がﾁｮｯﾄﾜｶﾙ ○ Software Catalogについてﾁｮｯﾄﾜｶﾙ ● 感情面 ○ Backstageにより興味を持って、やってみたいと思える

Platform Engineering Meetup Online #1 自己紹介 氏名：小泉 直人（ X : @koizum_ ） 経歴： - 富士通（2020/04~） - Gunosy（2022/01~） 業務：SRE - SLI／SLO周りやセキュリティに関する部分を主に担当 趣味：音楽、映画、 MLB（トロント・ブルージェイズ）

Platform Engineering Meetup Online #1 Software Catalogについて

Software Catalogについて はじめに こんなことありませんか？ ● ● ● ● 特定のリポジトリ、クラウドリソースにおいて、どのチームがオーナーシップを持ってい るかわからず、問い合わせ先がわからない オーナーが不明瞭で、リポジトリが長らくメンテナンスされていない どのリポジトリでどのクラウドリソースを管理しているかがわかりづらい どのリポジトリが依存関係にあるのかがわからない こんな問題を改善してくれるのが Backstageのソフトウェアカタログ

Software Catalogについて Software Catalogとは 各リポジトリのソフトウェアや各クラウドサービスのリソースに関する所有権とメタデータを集 約し、Backstageのポータルに可視化する機能 具体的には、該当のリポジトリやクラウドリソースがどのチームの所有物なのか、どのリポジ トリ、リソースに依存しているかを確認することができます 動線の集約が可能になり、検索容易性を上げ、エンジニアの認知負荷の低減を行うことがで きる

Software Catalogについて Software Catalogとは Portal画面からソフトウェアの Owner、依存関係などが一目で 見てわかる https://demo.backstage.io/

• https://demo.backstage.io/

Software Catalogについて Software Catalogのユースケース ● ● ● マイクロサービスアーキテクチャを採用している組織に特に有効 ○ リポジトリが分散している状態のなかで、その情報を Backstageに集約し、それ ぞれのOwner、依存関係を可視化するのに役立つ ○ 開発者はサービスに関する情報を 1つの場所で確認できる 複数のチームが存在し、それぞれが独立して開発を行っている組織に有効 ○ 技術スタックや開発手法が異なる場合、システムのメタデータを Backstageに集 約することで一元的に管理・確認することができる 新入社員のオンボーディングにも使える

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

Software Catalogについて エンティティとは Backstageにおけるエンティティは、ソフトウェア開発に関連する様々な要素や情報を表しま す。Backstageのエンティティは、特定のソフトウェアやサービス、 API、インフラリソースなどを 指します。 エンティティは System ModelというBackstageの概念に基づいて分類されており、各エンティ ティを用いて、複数のソフトウェアやサービス、 API、インフラリソースの依存関係や所有権を 表現します。

Platform Engineering Meetup Online #1 System Modelについて

System Modelについて System Modelとは Backstage上でシステムコンポーネントの依存関係や所有権を表現するための概念で、以下 のようなエンティティを用いてシステムをモデル化します （引用元: Backstage - System Model）

• https://backstage.io/docs/features/software-catalog/system-model#ecosystem-modeling

System Modelについて System Modelとは 右図のような関係で、以下のエンティティの 種類があります ● ● ● ● ● ● ● Component API Resource System Domain Group/User Location

Platform Engineering Meetup Online #1 各エンティティとそのフォーマットについて

各エンティティとそのフォーマットについて 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>

各エンティティとそのフォーマットについて 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” …

各エンティティとそのフォーマットについて 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 …

• https://github.com/hoge/&lt;repository_name&gt;/blob/&lt;default_branch_name&gt;/swagger/swagger.json

各エンティティとそのフォーマットについて Kind: Resource Component（ソフトウェア）が動作するために必要なインフラリソース（コンピュートリソース、 データベース、ストレージなど）を指します。 各インフラリソースと１対１対応させます。環境が複数ある場合には、全環境分を定義する必 要があります。異なる複数の AWSアカウントなどに同名のリソースが存在する可能性がある ため、metadata.namespaceを追加することで衝突を回避します。 apiVersion: backstage.io/v1alpha1 kind: Resource metadata: namespace: <namespace_name> name: <resource_name> spec: type: aws_s3_bucket …

各エンティティとそのフォーマットについて 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>

各エンティティとそのフォーマットについて Kind: System ソフトウェアやサービスを統合して構成するシステム全体を表し、これまで紹介した Component, API, Resourceの集合体をSystemとして定義します。 定義の粒度については、必ずしも Componentに合わせる必要はありませんが、何らか認識 しやすい粒度に分解しておくと理解しやすいです。 apiVersion: backstage.io/v1alpha1 kind: System metadata: namespace: <namespace_name> name: <system_name> spec: …

各エンティティとそのフォーマットについて 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>

各エンティティとそのフォーマットについて 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を指定

各エンティティとそのフォーマットについて 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]

各エンティティとそのフォーマットについて ここで一旦Break リポジトリのトップレベルに、これまで紹介したエンティティを定義した catalog-info.yamlを配 置することで、 Backstageにエンティティを登録できます ただ、catalog-info.yamlが巨大になってしまい、可読性が著しく低下してしまう可能性があり ます

各エンティティとそのフォーマットについて ディレクトリ構成 以下のように、それぞれのエンティティでディレクトリを分けて記述し、ルートディレクトリの 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 ## チームメンバー

各エンティティとそのフォーマットについて 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

• https://github.com/koizumi/backstage/blob/main/domains/hoge-domain.yaml
• https://github.com/koizumi/backstage/blob/main/systems/hoge-system.yaml
• https://github.com/koizumi/backstage/blob/main/groups/team-a.yaml
• https://github.com/koizumi/backstage/blob/main/groups/team-b.yaml
• https://github.com/koizumi/backstage/blob/main/users/michael.yaml

Platform Engineering Meetup Online #1 課題と解決事例の紹介

おさらい 課題と解決事例の紹介 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を手動 で定義するのは中々に 骨が折れる作業

課題と解決事例の紹介 Resourceエンティティの自動登録 Terraformで管理しているリソースを、 tfstate.jsonのデータから Resource Catalog （catalog-info.yaml）を自動生成するツールを作成しています tfstate.json convert.py catalog-info.yaml

課題と解決事例の紹介 [参考] convert.pyについて 以下のように、引数として指定することで、 tfstate.jsonで定義されている Terraformリソース を、BackstageのResource Catalogに変換し、catalog-info.yamlに出力することができます python ./convert.py \ --namespace ${{ namespace_name }} \ --input ./tfstate.json \ --output ./catalog-info.yaml

課題と解決事例の紹介 生成結果例 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'

課題と解決事例の紹介 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>

課題と解決事例の紹介 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

課題と解決事例の紹介

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 }

課題と解決事例の紹介

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,
}),
);

Platform Engineering Meetup Online #1 まとめ

Platform Engineering Meetup Online #1 まとめ ● Software Catalogを定義する上で重要な System Modelの概念について紹介 ● 各エンティティについて、それぞれの YAML Formatについて紹介 ● カタログファイルを定義する上での課題の解決事例を紹介 ○ Terraformのtfstate.jsonからResource Catalogを自動生成 ○ AWS S3 Integrationを用いてS3のカタログファイルを Backstageへ登録

Platform Engineering Meetup Online #1 入門Backstage System Modelの理解と活用方法 Naoto Koizumi , Gunosy Inc.