みなさんこんにちは。ACS事業部 Backstage Enthusiast の亀崎です。
今回のテーマは Backstage 。Backstageについては、これまで数年にわたって何度もご紹介していますので皆さんご存知ですよね？？
もし万が一ご存知ないという方がいましたらまずは以下の記事をご覧になってください。
ソフトウェアカタログの登録更新処理
Backstageの一番の機能はソフトウェアカタログです。そのソフトウェアカタログの情報は GitHub 等のリポジトリに作成・保管しておくものです。 今回はソフトウェアカタログの登録更新処理にフォーカスし、その内容と起きうる課題、その解決策についてご紹介していきたいと思います。
カタログ登録処理
Backstageではカタログの登録処理は次の２つの種類が用意されています。
- 手動登録
- Auto DiscoveryによるPull型同期処理
手動登録は皆様もご存知の「Register Existing Component」のボタンから登録するものです。
こちらからカタログ情報のURLを指定することで登録をすることができます。
またこれと類似の処理として、Scaffolder(Software Template) の register acitonもまた、ユーザーの操作をトリガーにカタログ情報を登録する機能になります。
もう１つがAuto discovery機能です。こちらは、定期的にGitHub Organization下のすべてのリポジトリを検索し、指定されたカタログファイルある場合は登録処理を行うというものです。指定されたファイル名で作成しておけば自動的に登録されるので便利ではあるのですが、定期的にGitHubのRepositoryへアクセスするため、GitHub Organization下のリポジトリが多くなると、後述するGitHub APIのRate Limitが問題となることがあります。
更新処理
続いて更新処理です。Backstageではリポジトリ上のカタログ情報との同期方法として以下の３種類が用意されています。
- 手動登録
- GitHub WebhookをトリガーとしたPush形式同期処理
- Auto DiscoveryによるPull型同期処理
先に紹介した手動登録画面で登録済みのURLを指定した場合、最新の内容に沿って更新を行います。これが最初の更新処理です。
GitHubはリポジトリの更新イベント等をWebhookでその内容を送信することができます。BackstageではこのGitHub Webhookを受信して、登録されたカタログ情報が更新された場合は、その内容を反映することができます。これが２つ目の更新処理であるGitHub WebhookをトリガーとしたPush形式の同期処理です。
さらに３つ目の更新処理が、先に紹介したAuto Discovery機能です。 これにより定期的にPull型の同期処理を実行することができます。
Webhookを利用したPush形式同期処理の場合、GitHub側で更新処理が実行された場合のみ同期処理が行われるため問題がおきることはほぼありません。これに対してスケジュール実行によるPull形式同期処理では、GitHubのOrganizationの全リポジトリを検索するため、GitHub APIのRate Limitが問題になることがあります。
課題 ： GitHub rate limit
上記のようにカタログ情報の登録・更新処理にはAPIを通じてGitHubにアクセスします。このGitHub APIにはRate Limitが設定されています。
2025年7月現在、1時間あたり5,000アクセスが上限とされています（GitHub Enterprise版をご利用の場合は15,000アクセス）。
Backstageでは様々な形でGitHub上のデータにアクセスします。GitHub Organizationに多数のリポジトリが存在するような環境ではこのRate Limitに到達してしまうことが起こり得るのです。
こうしBackstage公式ドキュメントの記述では以下のようにBackstageのapp-config.yamlのスケジュール指定で以下の内容を指定することが例として記載されています。
schedule: frequency: { minutes: 35 } timeout: { minutes: 3 }
この指定により、Pull型の同期処理が35分毎に行われるようになります。
Auto Discoveryについても、catalog.providers.github内のschedule指定で同様の指定をすることで、検索処理の間隔を指定することができます。
ハイパフォーマンス向けBackstageの設定
大規模な環境での利用事例としてBackstageCON 2025 EUのセッションでSpotify社におけるCatalog strategyが紹介されていましたのでご紹介します。
そのStragegyとは Push型同期処理を中心とし、24時間に一度のPull型動機処理を実行する、というものです。 おそらくこの前提として、カタログ情報の新規登録は手動で行うよう運用しているものと思います。
GitHub Webhookをトリガーに、変更のあったリポジトリのみを対象とすることでGitHubへのアクセスが必要最低限に限定することができます。 ただしWebhookの処理で失敗した場合リカバリーすることができません。このため24時間に一度だけPull型の同期を実行するようにしていると考えられます。
こうすることで、GitHub APIのRate Limitに到達してしまうリスクを低減しています。これに加えて更新処理が必要最低限になるため、Backstageのプロセス負荷の低減も実現できます。
まとめ
組織内でBackstageを展開する場合にはこうした設定も重要になると思います。今回の情報が皆さんのお役に立てば幸いです。
Backstageには他にも開発者の認知負荷を低減する様々な機能が存在します。その効果も使い方次第でより大きくなります。 ご興味のある方がいらっしゃいましたらぜひ弊社までご連絡ください。よろしくお願いします。
www.ap-com.co.jp www.ap-com.co.jp
弊社では開発者ポータルBackstageのマネージドサービスである「PlaTT」も提供しております。 Backstageに興味があるという方もぜひご連絡をいただけると嬉しいです。
