Chapter 3. Custom plugins in Red Hat Developer Hub

Procedure

1. Navigate to the plugin’s root directory (not the dist-dynamic directory).

2. Run the following command to package the plugin into an OCI image:

   Example command to package an exported custom plugin

   $ npx @red-hat-developer-hub/cli@latest plugin package --tag quay.io/example/image:v0.0.1

   In the previous command, the --tag argument specifies the image name and tag.

3. Run one of the following commands to push the image to a registry:

   Example command to push an image to a registry using podman

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

   Example command to push an image to a registry using docker

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

   The output of the package-dynamic-plugins command provides the plugin’s path for use in the dynamic-plugin-config.yaml file.

Procedure

1. Navigate to the dist-dynamic directory.

2. Run the following command to create a tgz archive:

   Example command to create a tgz archive

   $ npm pack

   You can obtain the integrity hash from the output of the npm pack command by using the --json flag as follows:

   Example command to obtain the integrity hash of a tgz archive

   $ npm pack --json | head -n 10

3. Host the archive on a web server accessible to your RHDH instance, and reference its URL in the dynamic-plugin-config.yaml file as follows:

   Example dynamic-plugin-config.yaml file

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

4. Run the following command to package the plugins:

   Example command to package a dynamic plugin

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

   Tip

   To create a plugin registry using HTTP server on OpenShift Container Platform, run the following commands:

   Example commands to build and deploy an HTTP server in OpenShift Container Platform

   $ 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. Configure your RHDH to use plugins from the HTTP server by editing the dynamic-plugin-config.yaml file:

   Example configuration to use packaged plugins in RHDH

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

Procedure

1. Navigate to the dist-dynamic directory.

2. Run the following command to publish the package to your private NPM registry:

   Example command to publish a plugin package to an NPM registry

   $ npm publish --registry <npm_registry_url>

   Tip

   You can add the following to your package.json file before running the export command:

   Example package.json file

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

   If you modify publishConfig after exporting the dynamic plugin, re-run the plugin export command to ensure the correct configuration is included.

Procedure

1. To retrieve plugins from an authenticated registry, complete the following steps:

   1. Log in to the container image registry.

      podman login <registry>

   2. Verify the content of the auth.json file created after the login.

      cat ${XDG_RUNTIME_DIR:-~/.config}/containers/auth.json

   3. Create a secret file using the following example:

      oc create secret generic _<secret_name>_ --from-file=auth.json=${XDG_RUNTIME_DIR:-~/.config}/containers/auth.json 

      1

      • For an Operator-based deployment, replace <secret_name> with dynamic-plugins-registry-auth.
      • For a Helm-based deployment, replace <secret_name> with <Helm_release_name>_-dynamic-plugins-registry-auth.

2. Define the plugin with the oci:// prefix in the following format in dynamic-plugins.yaml file:

   oci://<image_name>:<tag>!<plugin_name>

   Example configuration in dynamic-plugins.yaml file

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

3. To perform an integrity check, use the image digest in place of the tag in the dynamic-plugins.yaml file as shown in the following example:

   Example configuration in dynamic-plugins.yaml file

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

4. To apply the changes, restart the RHDH application.

Procedure

1. Specify the archive URL and its integrity hash in the dynamic-plugins.yaml file using the following example:

   Example configuration in dynamic-plugins.yaml file

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

2. To apply the changes, restart the RHDH application.

Procedure

1. Run the following command to obtain the integrity hash from the NPM registry:

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

2. Specify the package name, version, and its integrity hash in the dynamic-plugins.yaml file as follows:

   Example configuration in dynamic-plugins.yaml file

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

3. If you are using a custom NPM registry, create a .npmrc file with the registry URL and authentication details:

   Example code for .npmrc file

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

4. When using OpenShift Container Platform or Kubernetes:

   • Use the Helm chart to add the .npmrc file by creating a secret. For example:

     Example secret configuration

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

     1

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

     1 1

     Replace <release_name> with your Helm release name. This name is a unique identifier for each chart installation in the Kubernetes cluster.

   • For RHDH Helm chart, name the secret using the following format for automatic mounting:

     <release_name>-dynamic-plugins-npmrc

5. To apply the changes, restart the RHDH application.

Procedure

1. To add your custom dynamic plugins to Red Hat Developer Hub. you must update the dynamic-plugins.yaml file by using the following configuration that is generated from the npx @red-hat-developer-hub/cli@latest plugin package command:

   plugins:
     - package: oci://quay.io/_<user_name>_/entity-feedback-plugin:0.5.0!backstage-community-plugin-entity-feedback
       disabled: false
   
     - package: oci://quay.io/_<user_name>_/entity-feedback-plugin-backend:0.6.0!backstage-community-plugin-entity-feedback-backend
       disabled: false

Procedure

1. You need to update the pluginConfig section of your dynamic-plugins.yaml file to specify how the Entity Feedback should be added to the Red Hat Developer Hub UI.

   dynamic-plugins.yaml file fragment

   - package: oci://quay.io/_<user_name>_/entity-feedback-plugin:0.5.0!backstage-community-plugin-entity-feedback
     disabled: false
     pluginConfig:
       dynamicPlugins:
         frontend:
           backstage-community.plugin-entity-feedback:
             entityTabs:
               - mountPoint: entity.page.feedback
                 path: /feedback
                 title: Feedback
             mountPoints:
               - config:
                   layout:
                     gridColumn: 1 / -1
                 importName: StarredRatingButtons
                 mountPoint: entity.page.feedback/cards
               - config:
                   layout:
                     gridColumn: 1 / -1
                 importName: EntityFeedbackResponseContent
                 mountPoint: entity.page.feedback/cards
               - config:
                   layout:
                     gridColumnEnd:
                       lg: span 6
                       md: span 6
                       xs: span 6
                 importName: StarredRatingButtons
                 mountPoint: entity.page.overview/cards

   where:

   backstage-community.plugin-entity-feedback:entityTabs

   Enter the entityTabs array to define a new tab, named “Feedback” on the Entity Overview screen in Red Hat Developer Hub.

   frontend:mountPoints

   This array defines the following configurations to mount React components exposed by the plugin:

   • The StarredRatingButtons component is added to the new Feedback tab defined in entityTabs.
   • Similar to the StarredRatingButtons, the EntityFeedbackResponseContent is mounted on the Feedback tab.
   • The StarredRatingButtons is added to the default Overview tab for each entity.

2. To complete installing the Entity Feedback plugins, you must redeploy your Red Hat Developer Hub instance.