背景
開発チームが抱えるよくある課題として
- システムが変化する一方でドキュメントは更新されず腐る
- メンバーの流入出によって口伝でかろうじて継承された知見も失われる
- 検索性が良くないと過去のドキュメントが気づかれず、同じような内容のドキュメントが新規量産される
- 後から参加したメンバーはどちらが正のドキュメントか分からず混乱する
といったことが良くあります。
解決方法としては以下のように、GitHub＆ルールベースで管理するといった例があります。
また組織・システムが大きくなってくると認知負荷を低減するためにドメインで区切るような形でチームの分割が始まりますが、
- 異なるチームによってシステムが管理され、システムの依存関係を全て知っている人がいなくなる
- CxOレイヤが大規模イベント前に現状を把握したいときに都度時間がかかってしまう
- チームごとにドキュメントの品質・内容・管理方法が異なり、確認のための余計なコミュニケーションコストがかかる
となり、先程のドキュメント管理の課題と相まって生産性を低下させます。
このような状況で、総合的なソリューションとして生み出されたのがSpotifyのBackstageです。
Spotifyでは数百もの独立したマイクロサービスが存在し、それぞれが異なるチームによって管理されていました。
この複雑さを管理するため、Spotifyは開発プロセスを標準化し、チーム間の共有と協力を促進する内部ツールとしてBackstageを開発しました。
今回はそのBackstageについて説明します。
Backstageとは
Backstageは開発者ポータルで、コア機能としては以下の役割を持ちます。
| 機能 | 説明 |
|---|---|
| Software Catalog | システムコンポーネントの依存関係を可視化し、API IFやLinkなど情報を集約する |
| TechDocs | コンポーネントのドキュメントを集約する |
| Software Template | 新規コンポーネントを作る際のテンプレート |
それぞれを簡単に解説します。
Software Catalog
デモサイトを触ってみるのが一番わかり易いです。
https://demo.backstage.io/catalog
Software Catalogではシステムコンポーネントの情報を全て集約し可視化します。
このように情報が集約＆標準化（フォーマット等が統一）されるので、
- 初見のメンバーでも理解しやすい
- ドキュメントの検索性に依存しない
- 書く側も迷わずに書くことができる
といったメリットがあります。
TechDocs
TechDocsはコンポーネントのドキュメントを管理するものです。
TechDocsはGitHubのmdファイルを読み込んでポータル上で表示します。
ref: TechDocs Architecture | Backstage Software Catalog and Developer Platform
なので
- GitHubで管理できる
- レビュープロセスを踏める
- Issueと紐づけやすい
- 開発者が慣れていてハードルが低い
といったメリットがあります。
またPlantUMLやMermaidといった記法もプラグインでサポートしているので、シーケンス図や状態遷移図などもコードベースで管理できます。
Software Template
例えば新規サービスを作る際は、
- main関数の安全な起動・終了処理
- パッケージマネージャ
- ヘルスチェック処理
- モニタリングツールとの連携
- （モノリポでないなら）リポジトリの用意
- CI/CDの設定
- .editorconfig等
といった要素が既存のサービスと一緒なことが多いため、テンプレートがあった方が迅速に用意できます。
既存のものからコピペする場合は
- どこまでコピペすべきか分かりにくい
- 古い書き方のサービスを参考にしてしまうとそれが蔓延する
といった問題があるため、やはりテンプレートとして提供するのがベターです。
BackstageのTemplate機能はGitHubと連携してるので、そういったコード生成を自動的にコミットしたり新規リポジトリとして用意できます。
こちら3分程の動画ですがどんなことができるのかが分かります。
Plugins
Backstageの良いところは拡張性で、多くのPluginsが公式・コミュニティから提供されています。
Backstage Software Catalog and Developer Platform
Kubernetes
例えばKubernetes Pluginを入れれば、開発者ポータル上でサクッとPodの状態やマニフェストファイルの確認などができるので「あれ、デプロイできてない？」「環境変数適用されてない？」みたいな確認にも使えて便利です。
https://backstage.io/docs/features/kubernetes/
Bugsnag
Bugsnagなどのエラー検知ツールとも紐付けられるので、このサービスでどんなエラーが起きていたのかをすぐに把握できます。
https://roadie.io/backstage/plugins/bugsnag/
サービスが成長していくとこういったSaaS系ダッシュボードが増えていくため
- それぞれ別で見ないといけないので地味に時間を使う
- 途中から入ったメンバーはどのダッシュボードがあるのか、どれを見ればいいのか分からない
といったことが良くありますが、このように開発者ポータルにまとめることで解決できます。
まとめ
開発者ポータルBackstageがどんな課題背景から生まれ、それをどう解決しているのかメリットについて説明しました。
