はじめに
みなさんこんにちは。
先日（2024年8月21日）、Backstage v1.30.0 がリリースされました。
普段のリリースよりもRelease Noteの記載が多く、いくつかの機能が追加・変更されていることが推測されます。
今回はその内容を軽く取り上げつつ、実際にBackstage v1.30.0 にアップデートする際に手間取った経験から、アップデートする前にこれはやっておいたほうがよい、ということをご紹介したいと思います。
Backstage v1.30.0の変更内容
まずはリリースノートからv1.30.0の修正のポイントをご紹介します。
- New frontend system - Plugin Adoption
絶賛機能改善・品質向上中のNew frontend systemですが、「そろそろPluginユーザーの方は移行の準備を進めてくださいね」としています。また、すでにNew frontend system対応を進めている方はいくつか変更点があるので、それを修正する必要があります。私の手元にあるコードはまだNew frontend systemには対応していないこともあり、これに関する修正は特に発生しませんでした。ただ、そろそろ独自Pluginについては移行を検討する必要があると認識しました。 - Backend system deprecations and removals
今回は@backstage/backend-app-apiの定義がdeprecationとマークされました。利用している方は@backstage/backend-defaults/<service>を利用するようにと推奨されています。
今回おそらくいちばん影響を受けるのがUrlReaderです。すでにdeprecationとマークされていましたが、今回削除されました。利用している方は指定されているものに置き換える必要があります。 - Auth Sign n Resolver Priority
少し前のバージョンからResolverがconfで指定できるようになっていましたが、今回confでの指定が最優先されることになったようです。 - @backstage/cli
アップデート時に利用していたコマンドの動作が一部変更になりました。それがversions:bump時のduplicate moduleのチェックを実施しなくなったのと、versions:checkの削除 です。今後はユーザー自身でyarn dedupeなどを実施してくださいとのことです。 - @backstage/backend-test-utils
いくつかのコードが削除されています。指定された変更を行う必要があります。手元のコードではとくに実施するものはありませんでした。 - その他機能追加
個人的に前からきにしていた「Dynamic Backend Feature Loaders」が紹介されていました。またScaffolderのI18Nも実施されたようです。
アップデート前にしておくべきこと
さて本題です。v1.30にアップデートする前に実施すべきこととはなにか・・・。
アップデートで一番影響を受けるのが以前deprecationしたもののremovalです。どの程度影響があるかと思って何も考えずにいつものように yarn backstage-cli versions:bump したところ、package.jsonのアップデートは問題なくできたのですが、一部コードでエラーが発生しました。エラーになったところが主に removalの部分です。
deprecationの部分であれば、コードエディターがドキュメントを参照し、「代わりにXXXを使うように」といった指示を参照できますが、removalに関してはすでにコードがなくなっているためそうしたヒントが得られません。その結果、同修正したらよいのか戸惑ったりします。
これを避けるため、v1.30へのアップデートを行う前にdeprecation等の修正を行うことをおすすめします。アップデート前であればまだ修正のヒントが得られるため、修正も容易です。
ということで、 @backstage/backend-common を使っている部分を探し出し、deprecationとなっている部分を特定し、修正をかけていきます。ただし、ここで注意が必要です（私もここで失敗しました）。それはLegacyPlugin対応です。
LegacyPlugin対応についてはおそらく以下のようなインターフェースを使って、各種サービスをPluginに渡しているものと思います。
import { Logger } from 'winston'; import { Backend } from '@backstage/backend-app-api'; import { PluginCacheManager, PluginDatabaseManager, PluginEndpointDiscovery, TokenManager, UrlReader, } from '@backstage/backend-common'; import { Config } from '@backstage/config'; import { EventBroker, EventsService } from '@backstage/plugin-events-node'; import { PluginTaskScheduler } from '@backstage/backend-tasks'; import { PermissionEvaluator } from '@backstage/plugin-permission-common'; import { IdentityApi } from '@backstage/plugin-auth-node'; export type LegacyPluginEnvironment = { logger: Logger; database: PluginDatabaseManager; cache: PluginCacheManager; config: Config; reader: UrlReader; discovery: PluginEndpointDiscovery; tokenManager: TokenManager; scheduler: PluginTaskScheduler; permissions: PermissionEvaluator; identity: IdentityApi; eventBroker?: EventBroker, events?: EventsService; };
ここでbackend-commonで定義されているもの、およびEventBrokerがdeprecationとマークされていいると思います。 さきほどの方針でいえばこれらすべてを新しいものに置き換える修正をすることになりますが、それはNGです。 なぜなら、これらのサービスはLegacyなPlugin側で使われてるものであり、そのPlugin側が新しいバージョンに対応していないことが多いためです。
そこで、この部分の修正は 1.30.0 で削除される UrlReder だけを対象とします。deprecationのドキュメントには UrlReaderService を利用しろとなっていますので、その通りにします。幸いなことに私のところで利用している Pluginでは UrlReaderServiceでも受け付けてくれるようになっていたため、定義を書き換えるだけで修正は完了しました。
その他のbackstage-commonで定義されてるインターフェースは今回はそのままとします。（あとはLegacy PluginがNew Backend Systemに対応するのを待ちます）
この修正で動作確認まで行ってからあらためて 1.30.x へのアップデートを実施します。 すると今度は特にビルドエラーも発生せずに無事動作しました。
まとめ
今年に入ってNew Backend Systemへの移行が活発になり、Legacy CodeもDeprecationされている状況です。今後もバージョンアップごとに今回のようにコードのRemovalのためにビルドできないといった問題が発生する可能性があります。New Backend Systemもだいぶ安定しましたし、こうした状況を避けるため、LegacyなPluginは早期にNew Backend Systemへ移行したほうがよいでしょう。
また、今回New Frontend Systemについてもあらためてリリースノートで言及されたこともあり、徐々に移行の準備を進めたほうがよさそうです。 New Backend System以上にNew Frontend Systemは大きな移行作業になるのではと予想されますので、早めにキャッチアップして対応を進めたほうが良いでしょう。
1.30.xの内容のご紹介と、アップデートの際の注意事項は以上で終了です。本投稿が皆様のお役に立てれば幸いです。
本ブログでは様々なテーマでBackstageについて取り上げています。ぜひそちらもご覧ください。
最後に弊社ではBackstageの導入や運用をManagedで行うサービスを提供しています。Permission FrameworkのPolicyの定義方法のガイドなどもあわせて提供していきたいと考えておりますので、ご興味のある方はぜひご連絡ください。
それでは、またの機会にお会いしましょう。
