Node 20以降でBackstageを実行する場合の注意事項

問題の発端

先日、Backstageを実行する際のNodeJSのバージョンをv18からv20にアップデートしました。 するとScaffolder（Software Template）を実行するとエラーがブラウザで表示されるようになりました。

その内容は以下のとおりです。

When using Node.js version 20 or newer, the scaffolder backend plugin requires that it be started with the --no-node-snapshot option. 
Please make sure that you have NODE_OPTIONS=--no-node-snapshot in your environment.`

対応

指示に従ってコンテナイメージ作成時に以下の指定をしました。

  ENV NODE_ENV production
+ # When using Node.js version 20 or newer, the scaffolder backend plugin requires that it be started with the --no-node-snapshot option. 
+ # Make sure that you have NODE_OPTIONS=--no-node-snapshot in your environment
+ ENV NODE_OPTIONS --no-node-snapshot

chocott-backstageの修正例はこちらになります。

github.com

これをデプロイしたところ、問題は解消しました。

背景にあるもの

「この指定はなんだろう？」「いつからこうした対応が必要になったのだろう」「ドキュメントのどこかに記述があったのだろうか」と少し気になったので過去の記録をたどってみることにしまｓた。

Scaffolderの安全性確保（isolated-vmの利用）

Backstage v1.15（2023年7月公開）で Scaffolderに以下の変更が行われました。

github.com

The Scaffolder backend uses a sandboxing environment to run its nunjucks
templating in, for security reasons. This used to leverage the vm2 library,
but in this release it has been replaced by isolated-vm. This significantly
improves the confidence level in the sandbox implementation since it builds upon
v8 isolates directly. 
以下省略

実行時の安全性向上のために scaffolderでは isolated-vm というモジュールを利用するようになりました。

さて、このisolated-vmですが、そのREADMEを見るとnode v20以降を利用する場合はNODE_OPTIONSの指定が必要になります。

This project requires nodejs version 16.x (or later).

🚨 If you are using a version of nodejs 20.x or later, you must pass --no-node-snapshot to node.

github.com

説明としてはこの一文なのですが、この指定がNode v20以降ではとても重要です。

Backstage側での通知

Backstageの利用者側としてはPluginが参照しているモジュールすべての説明を確認するのは困難でしょう。 isolated-vmの上記のrequiirementに気づいた方も少なかったようです。 そこで以下のIssueがリポートされ、Backstageの公式ドキュメントが更新されることになりました。

github.com

backstage.io

If you're running Backstage with Node 20 or later, you'll need to pass the flag --no-node-snapshot to Node in order to use the templates feature. One way to do this is to specify the NODE_OPTIONS environment variable before starting Backstage: export NODE_OPTIONS=--no-node-snapshot

さらに、実行時に以下のエラーが出るようになりました。

    if (nodeVersion >= 20 && !isNoNodeSnapshotOptionProvided()) {
      throw new Error(
        `When using Node.js version 20 or newer, the scaffolder backend plugin requires that it be started with the --no-node-snapshot option. 
        Please make sure that you have NODE_OPTIONS=--no-node-snapshot in your environment.`,
      );
    }

github.com

結論としてBacstageの公式ドキュメントに記載はあったのですが、Node v18を使っているユーザーが「そろそろv20以降に変更しようか」と思ったときに、Backstageのすべてのドキュメントを確認するのも大変ですし、現実的ではありません。そうすると実行時に上記のようなエラーが表示されて驚く、といったことが起きるのではないかなと思います。しかもこれはScaffolderを実行しないと表示されない・・・。バージョンアップ作業ではなかなか気付けず、デプロイ公開後に気づくなんてことが起きることが予想されます。（私はそのような経験となりました）

まとめ

タイトルにある「Node 20以降でBackstageを実行する場合の注意事項」としては

「NODE_OPTIONS=--no-node-snapshot」をお忘れなく

だけでした。情報量としてはとても少ないのですが、同じようなことに遭遇する方をひとりでも減らしたいと記事にさせていただきました。

皆様のご参考になれば幸いです。