Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 1. Install dynamic plugins in Red Hat Developer Hub

The backend plugin manager package provides dynamic plugin support. This service scans a configured root directory (dynamicPlugins.rootDirectory in the app-config.yaml file) for dynamic plugin packages and loads them dynamically.

You can use the dynamic plugins that come preinstalled with Red Hat Developer Hub or install external dynamic plugins from a public NPM registry.

You can store the configuration for dynamic plugins in a ConfigMap object that your Backstage custom resource (CR) can reference.

Dynamic plugins might require you to configure certain Kubernetes resources. The documentation refers to these resources as plugin dependencies. For more information, see Dynamic plugins dependency management.

In Red Hat Developer Hub (RHDH), you can automatically create these resources when you apply the Backstage CR to the cluster.

Note

If the pluginConfig field references environment variables, you must define the variables in your <my_product_secrets> secret.

Procedure

  1. From the OpenShift Container Platform web console, select the ConfigMaps tab.
  2. Click Create ConfigMap.

  3. From the Create ConfigMap page, select the YAML view option in Configure via and edit the file, if needed.

    The following example shows a ConfigMap object using the GitHub dynamic plugin: 

    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-catalog-backend-module-github-dynamic'
        disabled: false
        pluginConfig:
          catalog:
            providers:
              github:
                organization: "${GITHUB_ORG}"
                schedule:
                  frequency: { minutes: 1 }
                  timeout: { minutes: 1 }
                  initialDelay: { seconds: 100 }
  4. Click Create.
  5. Go to the Topology view.

  6. Click the overflow menu for the Red Hat Developer Hub instance that you want to use and select Edit Backstage to load the YAML view of the Red Hat Developer Hub instance.

    Editing Backstage from the Topology view

  7. Add the dynamicPluginsConfigMapName field to your Backstage CR. For example: 

    apiVersion: rhdh.redhat.com/v1alpha5
kind: Backstage
metadata:
  name: my-rhdh
spec:
  application:
    dynamicPluginsConfigMapName: dynamic-plugins-rhdh
  8. Click Save.
  9. Navigate back to the Topology view and wait for the Red Hat Developer Hub pod to start.
  10. Click the Open URL icon to start using the Red Hat Developer Hub platform with the new configuration changes.

Verification

  • Ensure that the system loads the dynamic plugins configuration, by appending /api/dynamic-plugins-info/loaded-plugins to your Red Hat Developer Hub root URL and checking the list of plugins:

    The following example shows a list of plugins: 

    [
  {
    "name": "backstage-plugin-catalog-backend-module-github-dynamic",
    "version": "0.5.2",
    "platform": "node",
    "role": "backend-plugin-module"
  },
  {
    "name": "backstage-plugin-techdocs",
    "version": "1.10.0",
    "role": "frontend-plugin",
    "platform": "web"
  },
  {
    "name": "backstage-plugin-techdocs-backend-dynamic",
    "version": "1.9.5",
    "platform": "node",
    "role": "backend-plugin"
  },
]

1.2. Dynamic plugins dependency management
Copy link

Dynamic plugins configured for the Backstage custom resource (CR) might require Kubernetes resources called plugin dependencies, which RHDH creates automatically when you apply the CR.

You can configure plugin dependencies by including the required Kubernetes resources in the /config/profile/{PROFILE}/plugin-deps directory. You must add the required resources as Kubernetes manifests in YAML format in the plugin-deps directory.

Example showing how to add example-dep1.yaml and example-dep2.yaml as plugin dependencies: 

config/
  profile/
    rhdh/
     kustomization.yaml
     plugin-deps/
        example-dep1.yaml
        example-dep2.yaml
Note
  • If a resource manifest does not specify a namespace, the Operator creates it in the namespace of the Backstage CR.
  • Resources can contain {{backstage-name}} and {{backstage-ns}} placeholders. The Operator replaces the {{backstage-name}} placeholder with the name of the Backstage CR, and replaces the {{backstage-ns}} placeholder with the namespace of the Backstage CR.

The kustomization.yaml file must contain the following lines: 

configMapGenerator:
  - files:
      - plugin-deps/example-dep1.yaml
      - plugin-deps/example-dep2.yaml
    name: plugin-deps

1.2.2. Plugin dependencies infrastructure
Copy link

To install infrastructural resources that plugin dependencies require, for example, other Operators or custom resources (CR), you can include these in the /config/profile/{PROFILE}/plugin-infra directory.

To create these infrastructural resources (along with the Operator deployment), use the make plugin-infra command.

Note

On a production cluster, use this command with caution as it might reconfigure cluster-scoped resources.

1.2.3. Plugin configuration
Copy link

You must reference the plugin dependencies in the dependencies field of the plugin configuration when you apply the Backstage CR.

The Operator creates the resources that the files in the plugin-deps directory describe.

You can reference plugin dependencies in the dynamic-plugins ConfigMap that can either be part of the default profile configuration for all Backstage custom resources or part of the ConfigMap referenced in the Backstage CR. In Red Hat Developer Hub, you can include plugin dependencies in the dynamic plugin configuration.

Each dependencies.ref value can either match the full file name or serve as a prefix for the file name. The Operator creates the resources that the files in the plugin-deps directory describe that start with the specified ref value or exactly match it

Example showing how to add example-dep plugin dependency: 

apiVersion: v1
kind: ConfigMap
metadata:
  name: default-dynamic-plugins
data:
  dynamic-plugins.yaml: |
    includes:
      - dynamic-plugins.default.yaml
    plugins:
      - disabled: false
        package: "path-or-url-to-example-plugin"
        dependencies:
          - ref: example-dep

You can deploy a Developer Hub instance by using a Helm chart, which is a flexible installation method. With the Helm chart, you can load dynamic plugins into your Developer Hub instance without having to recompile your code or rebuild the container.

To install dynamic plugins in Developer Hub using Helm, add the following global.dynamic parameters in your Helm chart:

  • plugins: the dynamic plugins list intended for installation. By default, the list is empty. You can populate the plugins list with the following fields:

    • package: a package specification for the dynamic plugin package that you want to install. You can use a package for either a local or an external dynamic plugin installation. For a local installation, use a path to the local folder containing the dynamic plugin. For an external installation, use a package specification from a public NPM repository.
    • integrity (required for external packages): an integrity checksum in the form of <alg>-<digest> specific to the package. Supported algorithms include sha256, sha384 and sha512.
    • pluginConfig: an optional plugin-specific app-config.yaml YAML fragment. See plugin configuration for more information.
    • disabled: disables the dynamic plugin if set to true. Default: false.
    • forceDownload: Set the value to true to force a reinstall of the plugin, bypassing the cache. The default value is false.

    • pullPolicy: Similar to the forceDownload parameter and is consistent with other image container platforms. You can use one of the following values for this key:

      • Always: This value compares the image digest in the remote registry and downloads the artifact if it has changed, even if you downloaded the plugin before.

      • IfNotPresent: This value downloads the artifact if it is not already present in the dynamic-plugins-root folder, without checking image digests.

        Note

        The pullPolicy setting is also applied to the NPM downloading method, although Always will download the remote artifact without a digest check. The existing forceDownload option remains functional, however, the pullPolicy option takes precedence. The forceDownload option might be deprecated in a future Developer Hub release.

  • includes: a list of YAML files using the same syntax.
Note

The system merges the plugins list in the includes file with the plugins list in the main Helm values. If both plugins lists mention a plugin package, the plugins fields in the main Helm values override the plugins fields in the includes file. The default configuration has the dynamic-plugins.default.yaml file, which has all of the dynamic plugins preinstalled in Developer Hub, whether enabled or disabled by default.

The following examples show how to configure the Helm chart for specific types of dynamic plugin installations.

Configuring a local plugin and an external plugin when the external plugin requires a specific configuration: 

global:
  dynamic:
    plugins:
      - package: <alocal package-spec used by npm pack>
      - package: <external package-spec used by npm pack>
        integrity: sha512-<some hash>
        pluginConfig: ...

Disabling a plugin from an included file: 

global:
  dynamic:
    includes:
      - dynamic-plugins.default.yaml
    plugins:
      - package: <some imported plugins listed in dynamic-plugins.default.yaml>
        disabled: true

Enabling a plugin from an included file: 

global:
  dynamic:
    includes:
      - dynamic-plugins.default.yaml
    plugins:
      - package: <some imported plugins listed in dynamic-plugins.custom.yaml>
        disabled: false

Enabling a plugin that an included file disables: 

global:
  dynamic:
    includes:
      - dynamic-plugins.default.yaml
    plugins:
      - package: <some imported plugins listed in dynamic-plugins.custom.yaml>
        disabled: false

You can install external plugins in an air-gapped environment by setting up a custom NPM registry.

You can configure the NPM registry URL and authentication information for dynamic plugin packages by using a Helm chart. For dynamic plugin packages obtained through npm pack, you can use a .npmrc file.

Using the Helm chart, add the .npmrc file to the NPM registry by creating a secret. For example: 

apiVersion: v1
kind: Secret
metadata:
  name: <release_name>-dynamic-plugins-npmrc
type: Opaque
stringData:
  .npmrc: |
    registry=<registry_link>
    //<registry_link>:_authToken=<auth_token>
          ...

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

Red Hat Developer Hub (RHDH) uses dynamic plugins that Red Hat distributes as Open Container Initiative (OCI) artifacts. In disconnected or restricted environments, you must mirror these plugin artifacts to a registry accessible by your cluster.

To mirror dynamic plugin OCI artifacts for deployments in restricted environments, use the mirror-plugins.sh script.

1.6.1. Prerequisites
Copy link

  • You have installed Skopeo 1.20 or later. Use Skopeo for multi-arch image operations and manifest conversion.
  • You have installed tar 1.35 or later. Use GNU tar for extracting image layers.
  • You have installed jq 1.7 or later. Use jq for JSON parsing and manipulation. See Download jq.
  • You have installed Podman 5.6 or later. Use Podman for building catalog index images.
  • You have authenticated to the source registry, for example, quay.io or registry.redhat.io for pulling plugin artifacts.
  • If mirroring directly to a registry using --to-registry, you have authenticated to the target registry.
Note

After mirroring completes, the script generates a rhdh-plugin-mirroring-summary.txt file containing mappings of all mirrored plugins. Use this file to reference the correct mirrored plugin URLs when configuring your RHDH deployment.

For Operator deployments, you must configure the Backstage Custom Resource with the mirrored plugin references. For Helm deployments, you must update your values file with the mirrored plugin references.

Use this procedure to mirror plugins from a catalog index to a partially disconnected environment.

Procedure

  1. Download the mirroring script: 

    $ curl -sSLO https://raw.githubusercontent.com/redhat-developer/rhdh-operator/refs/heads/release-1.9/.rhdh/scripts/mirror-plugins.sh

  2. Run the mirroring script by using the bash command with the appropriate set of options:

    For example: 

    bash mirror-plugins.sh \
    --plugin-index oci://quay.io/rhdh/plugin-catalog-index:1.9 \
    --to-registry <my.registry.example.com>

    where:

    --to-registry <my.registry.example.com>
    Enter the URL for the target mirror registry where you want to mirror the catalog index.

This two-phase process exports plugins to disk from a connected host, transfers them to a restricted network, then imports them to your internal registry.

Procedure

  1. Download the mirroring script: 

    $ curl -sSLO https://raw.githubusercontent.com/redhat-developer/rhdh-operator/refs/heads/release-1.9/.rhdh/scripts/mirror-plugins.sh

  2. Export all plugins to a local directory:

    For example: 

    bash mirror-plugins.sh \
    --plugin-index oci://registry.access.redhat.com/rhdh/plugin-catalog-index:1.9 \
    --to-dir </tmp/rhdh-plugins>

    where:

    --to-dir </tmp/rhdh-plugins>
    Enter the local directory path.

  3. Import and push the plugins from the local directory to your internal registry:

    For example: 

    bash mirror-plugins.sh \
    --from-dir /tmp/rhdh-plugins \
    --to-registry <my.registry.example.com>

    where:

    --from-dir </tmp/rhdh-plugins>
    Enter the local directory path.
    --to-registry <my.registry.example.com>
    Enter the URL for the target mirror registry where you want to mirror the catalog index.

1.6.4. Mirror specific plugins by direct reference
Copy link

Use this procedure to mirror specific plugins by specifying their OCI URLs directly.

Procedure

  1. Download the mirroring script: 

    $ curl -sSLO https://raw.githubusercontent.com/redhat-developer/rhdh-operator/refs/heads/release-1.9/.rhdh/scripts/mirror-plugins.sh

  2. To mirror individual plugins by specifying their OCI URLs directly, run the mirroring script by using the bash command with the appropriate set of options:

    For example: 

    bash mirror-plugins.sh \
    --plugins oci://quay.io/rhdh-plugin-catalog/backstage-community-plugin-quay:1.8.0--1.22.1 \
              oci://quay.io/rhdh-plugin-catalog/backstage-community-plugin-github-actions:1.8.0--0.11.1 \
    --to-registry <my.registry.example.com>

    where:

    --to-registry <my.registry.example.com>
    Enter the URL for the target mirror registry where you want to mirror the catalog index.

1.6.5. Mirror plugins from a file
Copy link

Use this procedure to mirror plugins from a file containing a list of plugin URLs.

Procedure

  1. Create a text file listing the plugins to mirror (one per line), as follows:

    Example plugins.txt file: 

    oci://quay.io/rhdh-plugin-catalog/backstage-community-plugin-quay:1.8.0--1.22.1
oci://quay.io/rhdh-plugin-catalog/backstage-community-plugin-github-actions:1.8.0--0.11.1
oci://quay.io/rhdh-plugin-catalog/backstage-community-plugin-azure-devops:1.8.0--0.8.2

  2. Download the mirroring script: 

    $ curl -sSLO https://raw.githubusercontent.com/redhat-developer/rhdh-operator/refs/heads/release-1.9/.rhdh/scripts/mirror-plugins.sh

  3. Run the mirroring script by using the bash command with the appropriate set of options:

    For example: 

    bash mirror-plugins.sh \
    --plugin-list plugins.txt \
    --to-registry <my.registry.example.com>

    where:

    --plugin-list plugins.txt
    A text file listing the plugins to mirror.
    --to-registry <my.registry.example.com>
    Enter the URL for the target mirror registry where you want to mirror the catalog index.

1.6.6. Combine many plugin sources
Copy link

You can combine any of the plugin sources (for example, catalog index, plugin list file, and direct URLs) in a single mirroring operation. The script automatically deduplicates plugins if the same plugin is present in many sources.

Procedure

  1. Download the mirroring script: 

    $ curl -sSLO https://raw.githubusercontent.com/redhat-developer/rhdh-operator/refs/heads/release-1.9/.rhdh/scripts/mirror-plugins.sh

  2. To combine many plugin sources, run the mirroring script by using the bash command with the appropriate set of options:

    For example: 

    bash mirror-plugins.sh \
    --plugin-index oci://registry.access.redhat.com/rhdh/plugin-catalog-index:1.9 \
    --plugin-list custom-plugins.txt \
    --plugins 'oci://registry.internal.example.com/custom/my-plugin:1.0' \
    --to-registry registry.example.com

    where:

    --plugin-list custom-plugins.txt
    A text file listing the plugins to mirror.
    --to-registry <my.registry.example.com>
    Enter the URL for the target mirror registry where you want to mirror the catalog index.
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2026 Red HatBack to top