Backstageの新しいPlugin登録方法ご紹介

はじめに

皆さんこんにちは。エーピーコミュニケーションズ ACS事業部亀崎です。

以前 BackstageにNew Frontend Systemが登場し、導入がとても簡単になる、ということをご紹介しました。

techblog.ap-com.co.jp

今回から何回かにわけて、このNew Frontend Systemについて説明していきたいと思います。

今回は非常に簡単になった、新しいPlugin登録方法についてのご紹介です。

New Frontend Systemの基礎

Traditional Frontend System

以前の記事にも記載していますが、従来のBackstageの（Traditionalな）Frontendでは 必要な Frontend pluginを yarn install で appに追加するのとあわせて Reactのコードを記載することではじめてそのPluginが有効になっていました。

（React 記載の例）

  ...

  <Grid container spacing={3} alignItems="stretch">
    {entityWarningContent}
    <Grid item md={6}>
      <EntityAboutCard />
    </Grid>
    <Grid item md={6} xs={12}>
      <EntityCatalogGraphCard height={400} />
    </Grid>

    <EntitySwitch>
      <EntitySwitch.Case if={isGithubPullRequestsAvailable}>
        <Grid item md={6} xs={12}>
          <EntityGithubPullRequestsOverviewCard />
        </Grid>    
      </EntitySwitch.Case>  
    </EntitySwitch>

  ...

github.com

New Frontend SystemではこうしたReactコードを記述する必要がなくなります。 では具体的にはどうするのでしょうか？

実際に有効にするまでをみていきたいと思います。

New Frontend Systemでのインストール作業

今回は @backstage-community/plugin-entity-validation というpluginを導入するまでをみていきます。

なお、最新のBackstage create-app コマンドでコードを生成し、New Frontend Systemが有効になっていることを前提とします。

この場合、やるべきことは 以下の1行だけです。

yarn --cwd packages/app add @backstage-community/plugin-entity-validation

以上で終了です。上記でpluginをインストールしたら yarn start などで動かしてみてください。

するとサイドメニューに Entity Validation というメニューが増え、そこをクリックすると次のような画面が表示されるはずです。

インストール作業だけで機能が有効になっています。以前のようなコードを記述することもありません。 pluginの導入と、外部サービスに連携するためのConfigurationへ設定の記述だけです。 今回のEntity ValidationはConfiguration指定は不要のため、yarn add だけが必要な作業です。

いったいどういった仕組みに変わったのでしょうか？

Plugin Discoveryの仕組み

New Frontend Systemにすると、以下のような設定で自動的なPlugin検出機構が有効になります。

Plugin検出機構

app-configの app.packages にPlugin検出機構に対する指示を記載します。

app-config.yamlへのデフォルトの指定は以下の内容です。

app:
  packages: all

app.packagesにall を指定すると packages/app/packages.json に登録されているdependenciesからFrontend pluginを すべて有効なPluginとして登録します。

Plugin側でSidebarへの登録内容やコンテンツ表示内容が実装されているため、登録するだけで さきほどのEntity Validationのように機能が有効になるという仕組みです。

app.packages にはこのほか include や exclude というオプションを指定することもできます。 app.packages.include を指定した場合、packages.jsonで登録されているもののうち、指定されたものだけが Pluginとして有効になり、それ以外のものは有効になりません。

includesの例

app:
  packages:
    include:
      - '@backstage/plugin-catalog'
      - '@backstage/plugin-scaffolder'

app.packages.excludes を指定した場合、packages.jsonで登録されているもののうち 指定されたものは有効になりません。指定されていないものはすべて有効となります。

excludesの例

app:
  packages:
    exclude:
      - '@backstage/plugin-catalog'

詳細については以下のページに記載されています。

backstage.io

実際にどのように実行しているか興味のある方は以下のソースコードをご覧になるとよいでしょう。

github.com

ここまでをまとめるとTraditional Frontend SystemとNew Frontend Systemは以下のように変更されます。

項目	Traditional Frontend System	New Frontend System
Plugin 有効化	React コードを追加	yarn add だけ
Sidebar 登録	手動で記述	Plugin が自動登録
Plugin 検出	なし	app.packages による自動検出

Reactコードを書かなくても簡単に有効にできるようになったことで Pluginの導入が格段に楽になったことがおわかりいただけるのではないでしょうか。

導入したPluginのサイドバーの表示順序や、表示内容の細かいコンフィグレーションに関しても app-config.yaml に指定することで実現はできるのですが、今回は導入までの解説とし、 表示に関する詳細は、別の記事でご説明します。

Backend Systemは？

さて、今回ご紹介した New Frontend System の Plugin 検出機構ですが、 「Backend でも同じように使えないの？」と思った方もいらっしゃるのではないでしょうか。

デフォルトの Backend では、Plugin の有効化はソースコード上で行います。

packages/backend/src/index.ts の指定内容

...
// catalog plugin
backend.add(import('@backstage/plugin-catalog-backend'));
backend.add(import('@backstage/plugin-catalog-backend-module-github'));
backend.add(import('@backstage/plugin-catalog-backend-module-scaffolder-entity-model'));

// See https://backstage.io/docs/features/software-catalog/configuration#subscribing-to-catalog-errors
backend.add(import('@backstage/plugin-catalog-backend-module-logs'));

// permissions plugin
backend.add(import('@backstage/plugin-permission-backend'));
backend.add(
  import('@backstage/plugin-permission-backend-module-allow-all-policy')
);

...

単にbackend.add() するだけなので簡単といえば簡単なのですが、frontendのように app-config.yamlに指定するだけにできないものでしょうか？

実はFrontend と同様に app-config.yaml の設定だけで Plugin を有効化できる仕組みがすでに用意されています。

まずは packages/backend/src/index.ts の内容を以下のように変更します。

import { createBackend } from '@backstage/backend-defaults';
import { discoveryFeatureLoader } from '@backstage/backend-defaults';

const backend = createBackend();
backend.add(discoveryFeatureLoader);
...
backend.start();

これによりFrontend同様Backend側でも packages/backend/packages.json に登録されている Pluginが自動的に有効にできます。

app-config.yaml の指定は backend.packages です。

backend:
  packages: all
  // include/excludeの指定はFrontendと同等に可能

実際の実装は以下のところをご覧ください。

github.com

これで Frontend でも BackendでもPlugin登録の際にソースコードを変更する必要は なくなります。かなり簡単になりますね！

最後に

弊社では、Backstageのマネージドサービスである「PlaTT」 を提供しています。 開発者ポータルの前提となる Platform Engineeringの導入支援も行っております。 開発者体験を向上し、開発生産性を高めたいとご検討の皆様、ぜひ弊社までご相談ください。

www.ap-com.co.jp

www.ap-com.co.jp