Red Hat Developer Hub でのプラグインのインストールと表示

手順

1. プラグインのルートディレクトリー (dist-dynamic ディレクトリーではありません) に移動します。

2. プラグインを OCI イメージにパッケージ化するには、次のコマンドを実行します。

   エクスポートされたサードパーティープラグインをパッケージ化するコマンドの例

   npx @janus-idp/cli@latest package package-dynamic-plugins --tag quay.io/example/image:v0.0.1

   前のコマンドでは、--tag 引数でイメージ名とタグを指定します。

3. 次のいずれかのコマンドを実行して、イメージをレジストリーにプッシュします。

   podman を使用してイメージをレジストリーにプッシュするコマンドの例

   podman push quay.io/example/image:v0.0.1

   docker を使用してイメージをレジストリーにプッシュするコマンドの例

   docker push quay.io/example/image:v0.0.1

   package-dynamic-plugins コマンドの出力には、dynamic-plugin-config.yaml ファイルで使用するプラグインのパスが提供されます。

手順

1. dist-dynamic ディレクトリーに移動します。

2. tgz アーカイブを作成するには、次のコマンドを実行します。

   tgz アーカイブを作成するコマンドの例

   npm pack

   次のように --json フラグを使用して、npm pack コマンドの出力から整合性ハッシュを取得できます。

   tgz アーカイブの整合性ハッシュを取得するコマンドの例

   npm pack --json | head -n 10

3. RHDH インスタンスにアクセスできる Web サーバー上でアーカイブをホストし、次のように dynamic-plugin-config.yaml ファイルでその URL を参照します。

   dynamic-plugin-config.yaml ファイルの例

   plugins:
     - package: https://example.com/backstage-plugin-myplugin-1.0.0.tgz
       integrity: sha512-<hash>

4. プラグインをパッケージ化するには、次のコマンドを実行します。

   動的プラグインをパッケージ化するコマンドの例

   npm pack --pack-destination ~/test/dynamic-plugins-root/

   ヒント

   OpenShift Container Platform で HTTP サーバーを使用してプラグインレジストリーを作成するには、次のコマンドを実行します。

   OpenShift Container Platform で HTTP サーバーを構築およびデプロイするためのコマンド例

   oc project my-rhdh-project
   oc new-build httpd --name=plugin-registry --binary
   oc start-build plugin-registry --from-dir=dynamic-plugins-root --wait
   oc new-app --image-stream=plugin-registry

5. dynamic-plugin-config.yaml ファイルを編集して、HTTP サーバーからのプラグインを使用するように RHDH を設定します。

   RHDH でパッケージ化されたプラグインを使用するための設定例

   plugins:
     - package: http://plugin-registry:8080/backstage-plugin-myplugin-1.9.6.tgz

手順

1. dist-dynamic ディレクトリーに移動します。

2. 次のコマンドを実行して、パッケージをプライベート NPM レジストリーに公開します。

   プラグインパッケージを NPM レジストリーに公開するコマンドの例

   npm publish --registry <npm_registry_url>

   ヒント

   export コマンドを実行する前に、package.json ファイルに次の内容を追加できます。

   package.json ファイルの例

   {
     "publishConfig": {
       "registry": "<npm_registry_url>"
     }
   }

   動的プラグインをエクスポートした後に publishConfig を変更する場合は、export-dynamic-plugin コマンドを再実行して、正しい設定が含まれていることを確認します。

手順

1. dynamic-plugins.yaml ファイルで、次の形式で oci:// 接頭辞を持つプラグインを定義します。

   oci://<image-name>:<tag>!<plugin-name>

   dynamic-plugins.yaml ファイルの設定例

   plugins:
     - disabled: false
       package: oci://quay.io/example/image:v0.0.1!backstage-plugin-myplugin

2. REGISTRY_AUTH_FILE 環境変数をレジストリー設定ファイルのパスに設定して、プライベートレジストリーの認証を設定します。たとえば、~/.config/containers/auth.json または ~/.docker/config.json です。

3. 整合性チェックを実行するには、次のように dynamic-plugins.yaml ファイル内のタグの代わりにイメージダイジェストを使用します。

   dynamic-plugins.yaml ファイルの設定例

   plugins:
     - disabled: false
       package: oci://quay.io/example/image@sha256:28036abec4dffc714394e4ee433f16a59493db8017795049c831be41c02eb5dc!backstage-plugin-myplugin

4. 変更を適用するには、RHDH アプリケーションを再起動します。

手順

1. 次の例を使用して、dynamic-plugins.yaml ファイルにアーカイブ URL とその整合性ハッシュを指定します。

   dynamic-plugins.yaml ファイルの設定例

   plugins:
     - disabled: false
       package: https://example.com/backstage-plugin-myplugin-1.0.0.tgz
       integrity: sha512-9WlbgEdadJNeQxdn1973r5E4kNFvnT9GjLD627GWgrhCaxjCmxqdNW08cj+Bf47mwAtZMt1Ttyo+ZhDRDj9PoA==

2. 変更を適用するには、RHDH アプリケーションを再起動します。

手順

1. 次のコマンドを実行して、NPM レジストリーから整合性ハッシュを取得します。

   npm view --registry <registry-url> <npm package>@<version> dist.integrity

2. 次のように、dynamic-plugins.yaml ファイルでパッケージ名、バージョン、およびその整合性ハッシュを指定します。

   dynamic-plugins.yaml ファイルの設定例

   plugins:
     - disabled: false
       package: @example/backstage-plugin-myplugin@1.0.0
       integrity: sha512-9WlbgEdadJNeQxdn1973r5E4kNFvnT9GjLD627GWgrhCaxjCmxqdNW08cj+Bf47mwAtZMt1Ttyo+ZhDRDj9PoA==

3. カスタム NPM レジストリーを使用している場合は、レジストリー URL と認証の詳細を含む .npmrc ファイルを作成します。

   .npmrc ファイルの例コード

   registry=<registry-url>
   //<registry-url>:_authToken=<auth-token>

4. OpenShift Container Platform または Kubernetes を使用する場合は以下のようになります。

   • Helm チャートを使用してシークレットを作成して .npmrc ファイルを追加します。以下に例を示します。

     シークレット設定の例

     apiVersion: v1
     kind: Secret
     metadata:
       name: <release_name>-dynamic-plugins-npmrc 

     1

     
     type: Opaque
     stringData:
       .npmrc: |
         registry=<registry-url>
         //<registry-url>:_authToken=<auth-token>

     1

     <release_name> は Helm リリース名に置き換えます。この名前は、Kubernetes クラスター内の各チャートインストールの一意の識別子です。

   • RHDH Helm チャートの場合は、自動マウントのために次の形式を使用してシークレットに名前を付けます。

     <release_name>-dynamic-plugins-npmrc

5. 変更を適用するには、RHDH アプリケーションを再起動します。

1. サードパーティーのプラグインのソースコードを取得する: プラグインのリポジトリーのクローンを複製し、Todo プラグイン ディレクトリーに移動します。

   サードパーティーのプラグインのソースコードを入手する

   $ git clone https://github.com/backstage/community-plugins
   $ cd community-plugins/workspaces/todo
   $ yarn install

2. バックエンドおよびフロントエンドプラグインをエクスポートする: 次のコマンドを実行して、バックエンドプラグインをビルドし、動的読み込み用のパッケージ依存関係を調整し、自己完結型の設定スキーマを生成します。

   バックエンドプラグインをエクスポートする

   $ cd todo-backend
   $ npx @janus-idp/cli@latest package export-dynamic-plugin

   バックエンドプラグインコマンドのエクスポートの出力

   Building main package
     executing     yarn build ✔
   Packing main package to dist-dynamic/package.json
   Customizing main package in dist-dynamic/package.json for dynamic loading
     moving @backstage/backend-common to peerDependencies
     moving @backstage/backend-openapi-utils to peerDependencies
     moving @backstage/backend-plugin-api to peerDependencies
     moving @backstage/catalog-client to peerDependencies
     moving @backstage/catalog-model to peerDependencies
     moving @backstage/config to peerDependencies
     moving @backstage/errors to peerDependencies
     moving @backstage/integration to peerDependencies
     moving @backstage/plugin-catalog-node to peerDependencies
   Installing private dependencies of the main package
      executing     yarn install --no-immutable ✔
   Validating private dependencies
   Validating plugin entry points
   Saving self-contained config schema in /Users/user/Code/community-plugins/workspaces/todo/plugins/todo-backend/dist-dynamic/dist/configSchema.json

   次のコマンドを実行して、デフォルトの動的 UI 設定を設定し、フロントエンドプラグインアセットを作成し、フロントエンドプラグインの設定スキーマを生成できます。

   フロントエンドプラグインをエクスポートする

   $ cd ../todo
   $ npx @janus-idp/cli@latest package export-dynamic-plugin

   フロントエンドプラグインコマンドのエクスポートの出力

   No scalprum config. Using default dynamic UI configuration:
   {
     "name": "backstage-community.plugin-todo",
     "exposedModules": {
       "PluginRoot": "./src/index.ts"
     }
   }
   If you wish to change the defaults, add "scalprum" configuration to plugin "package.json" file, or use the '--scalprum-config' option to specify an external config.
   Packing main package to dist-dynamic/package.json
   Customizing main package in dist-dynamic/package.json for dynamic loading
   Generating dynamic frontend plugin assets in /Users/user/Code/community-plugins/workspaces/todo/plugins/todo/dist-dynamic/dist-scalprum
     263.46 kB  dist-scalprum/static/1417.d5271413.chunk.js
   ...
   ...
   ...
     250 B      dist-scalprum/static/react-syntax-highlighter_languages_highlight_plaintext.0b7d6592.chunk.js
   Saving self-contained config schema in /Users/user/Code/community-plugins/workspaces/todo/plugins/todo/dist-dynamic/dist-scalprum/configSchema.json

3. サードパーティーのプラグインをパッケージ化して公開する: 次のコマンドを実行してワークスペースディレクトリーに移動し、動的プラグインをパッケージ化して OCI イメージを構築します。

   OCI イメージをビルドする

   $ cd ../..
   $ npx @janus-idp/cli@latest package package-dynamic-plugins --tag quay.io/user/backstage-community-plugin-todo:v0.1.1

   OCI イメージビルドコマンドの出力

     executing     podman --version ✔
   Using existing 'dist-dynamic' directory at plugins/todo
   Using existing 'dist-dynamic' directory at plugins/todo-backend
   Copying 'plugins/todo/dist-dynamic' to '/var/folders/5c/67drc33d0018j6qgtzqpcsbw0000gn/T/package-dynamic-pluginsmcP4mU/backstage-community-plugin-todo
   No plugin configuration found at undefined create this file as needed if this plugin requires configuration
   Copying 'plugins/todo-backend/dist-dynamic' to '/var/folders/5c/67drc33d0018j6qgtzqpcsbw0000gn/T/package-dynamic-pluginsmcP4mU/backstage-community-plugin-todo-backend-dynamic
   No plugin configuration found at undefined create this file as needed if this plugin requires configuration
   Writing plugin registry metadata to '/var/folders/5c/67drc33d0018j6qgtzqpcsbw0000gn/T/package-dynamic-pluginsmcP4mU/index.json'
   Creating image using podman
     executing     echo "from scratch
   COPY . .
   " | podman build --annotation com.redhat.rhdh.plugins='[{"backstage-community-plugin-todo":{"name":"@backstage-community/plugin-todo","version":"0.2.40","description":"A Backstage plugin that lets you browse TODO comments in your source code","backstage":{"role":"frontend-plugin","pluginId":"todo","pluginPackages":["@backstage-community/plugin-todo","@backstage-community/plugin-todo-backend"]},"homepage":"https://backstage.io","repository":{"type":"git","url":"https://github.com/backstage/community-plugins","directory":"workspaces/todo/plugins/todo"},"license":"Apache-2.0"}},{"backstage-community-plugin-todo-backend-dynamic":{"name":"@backstage-community/plugin-todo-backend","version":"0.3.19","description":"A Backstage backend plugin that lets you browse TODO comments in your source code","backstage":{"role":"backend-plugin","pluginId":"todo","pluginPackages":["@backstage-community/plugin-todo","@backstage-community/plugin-todo-backend"]},"homepage":"https://backstage.io","repository":{"type":"git","url":"https://github.com/backstage/community-plugins","directory":"workspaces/todo/plugins/todo-backend"},"license":"Apache-2.0"}}]' -t 'quay.io/user/backstage-community-plugin-todo:v0.1.1' -f - .
       ✔
   Successfully built image quay.io/user/backstage-community-plugin-todo:v0.1.1 with following plugins:
     backstage-community-plugin-todo
     backstage-community-plugin-todo-backend-dynamic
   
   Here is an example dynamic-plugins.yaml for these plugins:
   
   plugins:
     - package: oci://quay.io/user/backstage-community-plugin-todo:v0.1.1!backstage-community-plugin-todo
       disabled: false
     - package: oci://quay.io/user/backstage-community-plugin-todo:v0.1.1!backstage-community-plugin-todo-backend-dynamic
       disabled: false

   OCI イメージをコンテナーレジストリーにプッシュする:

   $ podman push quay.io/user/backstage-community-plugin-todo:v0.1.1

   OCI イメージコマンドのプッシュの出力

   Getting image source signatures
   Copying blob sha256:86a372c456ae6a7a305cd464d194aaf03660932efd53691998ab3403f87cacb5
   Copying config sha256:3b7f074856ecfbba95a77fa87cfad341e8a30c7069447de8144aea0edfcb603e
   Writing manifest to image destination

4. サードパーティーのプラグインをインストールして設定する: dynamic-plugins.yaml ファイルに次のプラグイン定義を追加します。

   dynamic-plugins.yaml ファイル内のプラグイン定義

   packages:
    - package: oci://quay.io/user/backstage-community-plugin-todo:v0.1.1!backstage-community-plugin-todo
      pluginConfig:
        dynamicPlugins:
          frontend:
            backstage-community.plugin-todo:
              mountPoints:
                - mountPoint: entity.page.todo/cards
                  importName: EntityTodoContent
              entityTabs:
                - path: /todo
                  title: Todo
                  mountPoint: entity.page.todo
    - package: oci://quay.io/user/backstage-community-plugin-todo:v0.1.1!backstage-community-plugin-todo-backend-dynamic
      disabled: false