はじめに

Ateam Group Manager ＆ Specialist Advent Calendar 2020の2日目は株式会社エイチームライフスタイル執行役員CTOの @tsutormがお送りします。例年マニアックなネタで好評を頂いておりますので、今年もマイペースで行こうと思います。 :smile:

一応完全に理解した¹はネタです。

この記事の概要

エンジニア向けポータル Backstageをうまく使って社内外サービスの "あれどこ / これ誰が見てるの / 詳しいのだれ" を減らせそうだよ
Spotify社が作ったOSSでpluggableなreact-appとして見てもとっても勉強になるよ

Backstageとは

開発組織が関わるサービスが少なく開発チームも小規模で、1~2サービスだけ見ていれば良い場合はそれほど問題は起きづらいですが、複数のサービスを複数の組織が連携しながら見るような開発組織規模になってきた場合、次のような問題が起きやすくなります。

誰がメンテナか不明なミニ社内サービス (意外と重要な事をしている)
標準化の不備によるノウハウ欠如
全体把握不良によるオンボーディングの長期化
車輪の再開発

ありがちですよね。

Backstageとは、Spotify社で上記の課題を解消するため、4年前から開発され今年3月にOSS(Apache License, Version 2.0) として公開された、開発者向けポータルシステム²で、社内のソフトウェア資産(マイクロサービス、ライブラリ、データパイプライン、Webサイト、MLモデルなど)をサービスカタログとして管理することにより、開発者自身が民主的,自律的に上記問題へ対処し... 要するに快適開発ライフが維持できますというやつです。³

ThoughtWorks TECHNOLOGY RADAR Vol.23でも今回からAssess評価に追加されて今後注目されていくかと思いますが、意外とQiita含めて日本語での触ってみた事例が少ない状況でしたので、今回はざっと触って "完全に理解した" 感を皆さんと共有できればと思います。

主な機能

サービスカタログ(Backstage Service Catalog)

開発組織が関係するサービス等を"カタログ"としてポータルへまとめることができます。一覧は上記の感じです。
後述するタイプ別に大きく区分けされ、その中で自分がオーナーのサービス、関係が深い(スターをつけた)サービス、全体での一覧化や、タグ、キーワードでの検索UIがあり、カタログ化されたサービスを素早く見つけられる様になっています。

カタログで管理される主な項目は

基本情報
- 識別名と、その概要
- ライフサイクル
  - 実験的/非production: experimental
  - 本番稼働: production
  - 廃止予定: deprecated
- タイプ
  - (基本的に)APIを持つサービス service、 Webサイト website、ライブラリ library
- オーナーとなる人物(識別子としてはメールアドレス), 組織
- タグ(ex: typescript, rubyとか検索する際に使う
ソースリポジトリ
- github, gitlab, etc...
API仕様
- OpenAPI(v2,v3): openapi
- AsyncAPI: asyncapi
- GraphQL: graphql
- gRPC: grpc
関連する技術文書(TechDocs)

と言ったものを kubernetesのconfigに似たyaml形式で定義することによって、以下のようなダッシュボードから扱えるようになります。

apiVersion:backstage.io/v1alpha1kind:Componentmetadata:name:petstoredescription:Petstorespec:type:servicelifecycle:experimentalowner:pets@example.comimplementsApis:-petstore-streetlights-hello-world

こんな感じ

ソフトウェアテンプレート(Backstage Software Template)

記事作成時点ではまだα版機能です。

社内で新しくアプリケーションを開発し始めるときのテンプレートを管理できる機能です。ここから新規リポジトリを社内の所定リポジトリに向けて展開することで、いちいち「あのxxxってリポジトリのyyyをzzzに変えると今んとこ一番社内でいい感じの構成になるよ」みたいなのが撲滅されます。

今回はあまり触ってないので紹介としてはこの程度ですが、Cookiecutterを利用してテンプレート構成から所定のリポジトリに初期プロジェクトが自動展開されるような感じです。ちょっと後述します。

技術文書(Backstage TechDocs)

Markdown形式で、技術的なドキュメントを記載できる機能です。
これも今回あまり触ってないのでさらっと公式からイメージだけ

触ってみる

まぁともあれ触ってみましょう。公式のGetting Startedにわかりやすく書いてますが、node(v14), npx と python と yarn と docker がセットアップされてる必要があります。

それぞれの導入は割愛します。

公式からgit cloneする手順が書いてありますが、backstage自体のメンテをするわけではなければ、Create an AppからがBackstageを自分の所用に作っていく手順になるので、こちらで進めます。

(もちろん git cloneの手順でも動きます)

ローカルで動かしてみる

動作前提が揃っている状態で以下で終わりです。簡単。

$ npx @backstage/create-app

アプリ名とbackendに使うDB(PostgreSQLかSQLiteの二択)を指定すれば、後はスクリプトが走って終わりです。

$ npx @backstage/create-app
? Enter a name for the app [required] lifestyle
? Select database for the backend [required]
  PostgreSQL
❯ SQLite

Creating the app...

 Checking if the directory is available:
  checking      lifestyle ✔

 Creating a temporary app directory:
  creating      temporary directory ✔

 Preparing files:
  copying       .eslintrc.js ✔
  templating    .gitignore.hbs ✔
(中略)
  copying       EntityPage.tsx ✔

 Moving to final location:
  moving        lifestyle ✔

 Building the app:
  executing     yarn install✔
  executing     yarn tsc ✔

🥇  Successfully created lifestyle

See https://backstage.io/docs/tutorials/quickstart-app-auth to know more about enabling auth providers

アプリケーションとしては、フロントのReactAppとバックエンドにexpressでAPIが立ってる構成ですので、実行もそれぞれ行います

$ cd lifestyle
$ yarn start & # フロントアプリの起動# (割愛)$ yarn workspace backend start # バックエンドアプリの起動# (割愛)

あとはブラウザから http://localhost:3000/にアクセスすれば冒頭の画面が出てくるはずです。

アプリケーション全体の設定は app-config.yamlに定義されたものをロードして利用しています。
親切な事に、デモ用のexampleが豊富に入った app-config.yamlを配備してくれた状態になってるので、本来なら同階層の app-config.production.yamlを軸に自由に変えていく。というのがセオリーかと思います。

今回はさらっと触るので、このデモの環境をベースに進めます。

サービスカタログに手動で追加してみる

任意のエディタで app-config.yamlを開いて、catalog:まで読み進めてください。

catalog:rules:-allow:[Component,API,Group,User,Template,Location]locations:# Backstage example components-type:urltarget:https://github.com/backstage/backstage/blob/master/packages/catalog-model/examples/all-components.yaml

アプリ側ではAllで6つ, Ownedとして3つのアプリが表示されますが、ここでは target として githubのリンクが示されているだけです。

おもむろにリンクをブラウザで開いてもらうと、以下の yaml になっています。

apiVersion:backstage.io/v1alpha1kind:Locationmetadata:name:example-componentsdescription:A collection of all Backstage example componentsspec:type:githubtargets:-https://github.com/backstage/backstage/blob/master/packages/catalog-model/examples/components/artist-lookup-component.yaml-https://github.com/backstage/backstage/blob/master/packages/catalog-model/examples/components/petstore-component.yaml-https://github.com/backstage/backstage/blob/master/packages/catalog-model/examples/components/playback-order-component.yaml-https://github.com/backstage/backstage/blob/master/packages/catalog-model/examples/components/podcast-api-component.yaml-https://github.com/backstage/backstage/blob/master/packages/catalog-model/examples/components/queue-proxy-component.yaml-https://github.com/backstage/backstage/blob/master/packages/catalog-model/examples/components/searcher-component.yaml-https://github.com/backstage/backstage/blob/master/packages/catalog-model/examples/components/playback-lib-component.yaml-https://github.com/backstage/backstage/blob/master/packages/catalog-model/examples/components/www-artist-component.yaml-https://github.com/backstage/backstage/blob/master/packages/catalog-model/examples/components/shuffle-api-component.yaml

おー。なんとなく掴めましたかね。試しに、petstore-component.yamlを見に行きましょう。

apiVersion:backstage.io/v1alpha1kind:Componentmetadata:name:petstoredescription:Petstorespec:type:servicelifecycle:experimentalowner:pets@example.comimplementsApis:-petstore-streetlights-hello-world

はい。ここで冒頭のカタログの設定が現れました。Backstageではこの単位を Component と呼ぶようです。

petstore-component.yamlに相当するものを自分たちが開発しているサービスのリポジトリルートに catalog-info.yamlみたいにおいておいて、それを指し示してあげれば、自動的にBackstageのカタログプロセッサが解釈してリストとして表示してくれる・・・と。そういう機構になってます。

したがって、試しにご自身のgithubなんかに適当に上記を改変したものを突っ込んで、暫く待つと...

jwt-example追加されましたね！

今回は触れませんが、metadata.annotationsでTechDocsを関連付けたり、spec.implementsApisでOpenAPIで書いた仕様書をAPIとして公開したり、、Componentを起点に様々な情報を集約していくことができます。

ソフトウェアテンプレートの裏側(Cookiecutters)

他にも、組織内のベストプラクティスを詰め込んだソフトウェアテンプレートを登録しておいて、新規アプリを立ち上げる時にオレオレベスト構成じゃなく、組織としてのベスト構成を標準化する機構があります。

こいつ内部でどういう動きになっているか気になりますよね？(ならないですかね？)

./packages/backend/src/plugins/scaffolder.tsを見てもらうとわかるのですが cookiecutterというプロジェクトテンプレートのツールを使っています。
実際に動作させてる所はここですね

ちょっとまだ試せてないですが、cookiecutterの流儀に乗せればある程度いろんな環境が作れる(ためしてないですが、gem installとか走らせるならdocker側の調整も必要かな・・・)っぽいです。

独自のtemplaterの作成もできるようなんで、頑張れば何でもって感じですかね。

それ以外色々

コアコンポーネント以外にも TechRadarやCost Insightsなど、プラグインとして機能強化可能な仕組みと、それを取り巻くマーケットプレイスエコシステムもあり、拡張性は非常に高そうです。

またアプリケーション自体もLernaを利用した大きなReact + Typescriptなappで、デザインについてもBackstage DesignTeamが全体設計に基づいてマテリアルUIを採用していて参考になるかなと感じました。

ただ、記事作成時点でまだまだ仕様も変わるし３つのフェーズの最初が終わった段階だよ。となっています。本番利用はそれなりに人柱上等の前提で進めた方が良さそうです。

まとめ

ソフトウェア資産が増えてきて全体視界不良感の解消を目的として、開発者ポータル/サービスカタログツール Backstage注目してみても良いかなと思いました。
内部のアーキテクチャ Lerna, cookiecutterも面白いので見てみると ○
まだロードマップの前半だからご利用は計画的に！

次回告知

Ateam Group Manager ＆ Specialist Advent Calendar 2020の3日目は @rf_pがお送りします。
ニーズを捉えてMVPを超高速リリースする彼のアドカレ、是非ご期待ください！！