第3章 TechDocs アドオン

手順

1. OpenShift Container Platform Web コンソールの Developer パースペクティブから、ConfigMaps > Create ConfigMap をクリックします。
2. Create ConfigMap ページで、Configure via フィールドの YAML view オプションを選択します。

3. 新しく作成した ConfigMap に、デフォルトの backstage-plugin-techdocs-module-addons-contrib パッケージ設定を追加します。以下に例を示します。

   kind: ConfigMap
   apiVersion: v1
   metadata:
     name: dynamic-plugins-rhdh
   data:
     dynamic-plugins.yaml: |
       includes:
         - dynamic-plugins.default.yaml
       plugins:
         - package: ./dynamic-plugins/dist/backstage-plugin-techdocs-module-addons-contrib
           disabled: false
           pluginConfig:
             dynamicPlugins:
               frontend:
                 backstage.plugin-techdocs-module-addons-contrib:
                   techdocsAddons:
                     - importName: ReportIssue

   Copy to Clipboard

4. ConfigMap の techdocsAddons セクションで、指定したプラグインパッケージから追加する外部 TechDocs アドオンごとに importName: <external_techdocs_add-on> を追加します。以下に例を示します。

   kind: ConfigMap
   apiVersion: v1
   metadata:
     name: dynamic-plugins-rhdh
   data:
     dynamic-plugins.yaml: |
       includes:
         - dynamic-plugins.default.yaml
       plugins:
         - package: ./dynamic-plugins/dist/backstage-plugin-techdocs-module-addons-contrib
           disabled: false
           pluginConfig:
             dynamicPlugins:
               frontend:
                 backstage.plugin-techdocs-module-addons-contrib:
                   techdocsAddons:
                     - importName: ReportIssue
                     - importName: <external_techdocs_add-on>

   Copy to Clipboard

   ここでは、以下のようになります。

   <external_techdocs_add-on>

   インストールする外部 TechDocs アドオン (TextSize や LightBox など) を指定します。

5. Create をクリックします。
6. Web コンソールのナビゲーションメニューで、Topology をクリックします。
7. 使用する Red Hat Developer Hub インスタンスのオーバーフローメニューをクリックし、Edit Backstage を選択して、Red Hat Developer Hub インスタンスの YAML ビューを読み込みます。

8. Backstage CR で、dynamicPluginsConfigMapName: <dynamic_plugins_configmap> というキーと値のペアを追加します。以下に例を示します。

   apiVersion: rhdh.redhat.com/v1alpha3
   kind: Backstage
   metadata:
     name: my-rhdh
   spec:
     application:
   # ...
       dynamicPluginsConfigMapName: _<dynamic_plugins_configmap>_
   # ...

   Copy to Clipboard

   ここでは、以下のようになります。

   <dynamic_plugins_configmap>

   Red Hat Developer Hub インスタンスの動的プラグイン ConfigMap の名前を指定します (例: dynamic-plugins-rhdh)。

9. Save をクリックします。
10. Web コンソールのナビゲーションメニューで、Topology をクリックし、Red Hat Developer Hub の Pod が起動するまで待ちます。
11. Open URL アイコンをクリックして、新しい設定変更を適用した Red Hat Developer Hub プラットフォームの使用を開始します。

手順

1. Helm チャートを使用した動的プラグインのインストール に示されているように、Helm チャートで、動的プラグインをインストールするために必要な global.dynamic パラメーターを追加します。

   注記

   デフォルト設定には dynamic-plugins.default.yaml ファイルが含まれています。このファイルには、デフォルトで有効か無効かに関係なく、Red Hat Developer Hub にプリインストールされているすべての動的プラグイン (TechDocs アドオンを含む) が含まれています。

2. Helm チャートで、デフォルトの backstage-plugin-techdocs-module-addons-contrib パッケージ設定を追加します。以下に例を示します。

   global:
     dynamic:
       plugins:
         - package: ./dynamic-plugins/dist/backstage-plugin-techdocs-module-addons-contrib
           disabled: false
           pluginConfig:
             dynamicPlugins:
               frontend:
                 backstage.plugin-techdocs-module-addons-contrib:
                   techdocsAddons:
                     - importName: ReportIssue

   Copy to Clipboard

3. Helm チャートの techdocsAddons セクションで、指定したプラグインパッケージから追加する外部 TechDocs アドオンごとに importName: <external_techdocs_add-on> を追加します。以下に例を示します。

   global:
     dynamic:
       plugins:
         - package: ./dynamic-plugins/dist/backstage-plugin-techdocs-module-addons-contrib
           disabled: false
           pluginConfig:
             dynamicPlugins:
               frontend:
                 backstage.plugin-techdocs-module-addons-contrib:
                   techdocsAddons:
                     - importName: ReportIssue
                     - importName: <external_techdocs_add-on>

   Copy to Clipboard

   ここでは、以下のようになります。

   <external_techdocs_add-on>

   インストールする外部 TechDocs アドオン (TextSize や LightBox など) を指定します。

手順

1. 次のコマンドを入力して、サードパーティーのアドオンをインポートするために使用するサードパーティーのプラグインをインストールします。

   yarn install

   Copy to Clipboard
2. 使用するサードパーティーの TechDocs アドオンのソースコードを取得します。

3. 次のコマンドを使用して、TechDocs アドオンを動的プラグインとしてエクスポートします。

   npx @janus-idp/cli@latest package export-dynamic-plugin

   Copy to Clipboard
   注記

   @latest タグは、最新の機能および修正と互換性のある最新バージョンの @janus-idp/cli パッケージを取得します。Red Hat Developer Hub のバージョンと互換性のあるバージョンを使用してください。

4. サードパーティーの TechDocs アドオンを動的プラグインとしてパッケージ化するために、プラグインが保存されているルートディレクトリー (dist-dynamic ディレクトリーではない) に移動し、--tag オプションを指定して npx コマンドを実行し、イメージ名とタグを指定します。以下に例を示します。

   npx @janus-idp/cli@latest package package-dynamic-plugins --tag quay.io/<user_name>/<techdocs_add-on_image>:latest

   Copy to Clipboard
   注記

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

5. サードパーティーの TechDocs アドオンを Quay リポジトリーに公開するために、お使いの仮想化ツールに応じて次のいずれかのコマンドを使用して、イメージをレジストリーにプッシュします。

   • podman を使用するには、次のコマンドを入力します。

     podman push quay.io/<user_name>/<techdocs_add-on_image>:latest

     Copy to Clipboard

   • docker を使用するには、次のコマンドを入力します。

     docker push quay.io/<user_name>/<techdocs_add-on_image>:latest

     Copy to Clipboard

6. dynamic-plugins.yaml ファイルを開き、サードパーティーの TechDocs アドオンの設定を表示または変更します。以下に例を示します。

   plugins:
         - package: oci://quay.io/<user_name>/<techdocs_add-on_image>:latest!<techdocs_add-on_package>
           disabled: false
           pluginConfig:
             dynamicPlugins:
               frontend:
                <techdocs_add-on_package>
                   techdocsAddons:
                     - importName: <third-party_add-on_name>
                      config:
                         props:
                          <techdocs_add-on_property_key>: <techdocs_add-on_property_value>

   Copy to Clipboard

   以下は、

   <user_name>

   Quay ユーザー名または組織名を指定します。

   <techdocs_add-on_image>

   使用するサードパーティーアドオンのイメージの名前を指定します (例: mermaid)。

   <techdocs_add-on_package>

   パッケージを指定します (例: backstage-plugin-techdocs-addon-mermaid)。

   <third-party_add-on_name>

   使用するサードパーティーアドオンの名前を指定します (例: Mermaid)。

   <techdocs_add-on_property_key>

   サードパーティーアドオンに渡すことができるカスタムプロパティーの名前 (例: themeVariables) を指定します。プロパティーは各アドオンに固有です。1 つのアドオンに対して複数のプロパティーをリストできます。

   <techdocs_add-on_property_value>

   サードパーティーアドオンのプロパティーキーの値を指定します (例: lineColor: #000000)。