dynamic-plugins.md

Dynamic Plugins registry configuration

Dynamic plugins can be configured to be loaded from different registries, such as NPM or container registries.

NPM registry

For dynamic plugins packaged in an NPM registry, ensure the .npmrc file is properly configured. By default, RHDH uses https://registry.npmjs.org registry and supports additional user-defined .npmrc files via the NPM_CONFIG_USERCONFIG environment variable, pointing to /opt/app-root/src/.npmrc.dynamic-plugins/.npmrc .

The default RHDH configuration includes extra .npmrc settings in secret-files.yaml:

@redhat:registry=https://npm.registry.redhat.com

To use your own .npmrc configuration:

• Create a Secret with a .npmrc key containing the content of your .npmrc file.

apiVersion: v1
kind: Secret
metadata:
  name: my-npmrc-secret
type: Opaque
stringData:
  .npmrc: |
    @my:registry=https://npm.my-registry.com

• Mount the Secret to the install-dynamic-plugin container by adding the following to the Backstage CR:

apiVersion: rhdh.redhat.com/v1alpha5
#...
spec:
  application:
    extraFiles:
      secrets:
        - name: my-npmrc-secret
          mountPath: /opt/app-root/src/.npmrc.dynamic-plugins
          containers:
            - install-dynamic-plugins          

Container registry

TODO: Dynamic plugins can be configured to use container registries for authentication and image pulling. This section should cover the configuration options available for container registry integration with dynamic plugins.

Catalog Index Configuration

The operator supports loading default plugin configurations from an OCI container image (catalog index). For general information about how the catalog index works, see Using a Catalog Index Image for Default Plugin Configurations.

By default, the rhdh profile of operator injects the CATALOG_INDEX_IMAGE environment variable in the RHDH install-dynamic-plugins init container. To use a different catalog index image, such as a newer version or a mirrored image, use the extraEnvs field in your Backstage CR. See examples/catalog-index.yaml for a complete example.

Extra catalog index images

In addition to the primary catalog index image, you can configure extra catalog index images using the EXTRA_CATALOG_INDEX_IMAGES environment variable. This allows loading plugin configurations from multiple catalog index images. See Using extra catalog index images for more details on how RHDH handles this environment variables.

The value is a comma-separated list of entries. Each entry supports two forms:

• name=image_ref: Assigns an explicit name to the catalog index image, which controls the extraction subdirectory under /extensions/extra/<name>/.
• image_ref: A direct image reference without a name; the extraction directory is auto-generated from the image reference.

To configure extra catalog index images, use the extraEnvs field in your Backstage CR:

apiVersion: rhdh.redhat.com/v1alpha5
kind: Backstage
metadata:
  name: my-backstage
spec:
  application:
    extraEnvs:
      envs:
        - name: EXTRA_CATALOG_INDEX_IMAGES
          value: "rhdh-community=quay.io/rhdh-community/plugin-catalog-index:1.10,registry.example.com/rhdh-catalog:latest"
          containers:
            - install-dynamic-plugins

Extensions Catalog Entities

Starting from version 1.9, the rhdh profile of the operator instructs the RHDH install-dynamic-plugins init container to extract catalog entities from the catalog index image to a new /extensions volume mount by default. This allows the extensions backend providers to automatically discover plugin metadata for display in the RHDH Extensions UI.

The extraction directory can be configured via the CATALOG_ENTITIES_EXTRACT_DIR environment variable in the install-dynamic-plugins init container.

More details in Catalog Entities Extraction.

Supported Package URL Formats

Format	Type	Description
ref://plugin-name	Catalog reference	Look up plugin by name, returns full package URL
oci://...{{inherit}}	Catalog reference	Look up plugin by name, returns full package URL
oci://...	Direct link	OCI image reference (no resolution)
https://...	Direct link	HTTPS URL to plugin archive
http://...	Direct link	HTTP URL to plugin archive
./path	Direct link	Local filesystem path

Plugin URL References

The operator optionally supports special URL reference syntax in plugin package URLs, allowing users to reference plugins from the default configuration by name.

TODO: document Operator Dynamic Plugins processing mode

Operator behavior:

• The operator resolves all references during ConfigMap merge (before passing to the init container)
• If a reference cannot be resolved, the operator returns an error and the Backstage CR will not reconcile
• Both reference types use name-based matching - only the plugin name matters for lookup

Ref Reference (ref://)

Look up a plugin by name and use its full package URL from the default configuration.

plugins:
  - package: "ref://backstage-plugin-catalog"
    pluginConfig:
      # your config overrides

Inherit Reference (:{{inherit}})

Look up a plugin by name and use its full package URL from the default configuration. The registry/path in your URL is ignored - only the plugin name matters for matching.

plugins:
  # These all match the same base plugin (backstage-plugin-catalog):
  - package: "oci://quay.io/rhdh/backstage-plugin-catalog:{{inherit}}"
  - package: "oci://any-registry/path/backstage-plugin-catalog:{{inherit}}"

Since v0.11.0: Both ref:// and :{{inherit}} use name-based matching (plugin name only, registry/path ignored). This behavior is slightly different from what is described in OCI Package Version Inheritance which documents the RHDH init-container behavior (full URL matching).

Dynamic plugins dependency management

Overview

Dynamic plugins configured for the Backstage CR may require certain Kubernetes resources to be configured to make the plugin work. These are referred to as 'plugin dependencies'. Starting from version 1.7, it is possible to automatically create these resources when the Backstage CR is applied to the cluster.

Profile Configuration

Plugin dependency configuration for a specific profile is done via the /config/profile/{PROFILE}/plugin-deps directory. To enable this, the administrator should place the required resources as Kubernetes manifests in YAML format within plugin-deps directory.

Example Directory Structure:

config/
  profile/
    rhdh/
     kustomization.yaml
     plugin-deps/
        example-dep1.yaml
        example-dep2.yaml

Here, example-dep1.yaml and example-dep2.yaml are the plugin dependencies for the example plugin.

Notes:

• If a resource manifest does not specify a namespace, it will be created in the namespace of the Backstage CR.
• Resources may contain {{backstage-name}} and {{backstage-ns}} placeholders, which will be replaced with the name and namespace of the Backstage CR, respectively.

The kustomization.yaml file should contain the following lines:

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

Plugin dependencies infrastructure

If plugin dependencies require infrastructural resources (e.g. other Operators and CRs to be installed) and if the User (Administrator) wants it to be deployed (see Note below), they can be specified in the /config/profile/{PROFILE}/plugin-infra directory. To create these resources (along with the operator deployment), use the make plugin-infra command.

Note: Be cautious when running this command on a production cluster, as it may reconfigure cluster-scoped resources.

Plugin configuration

To create the plugin dependencies when the Backstage CR is applied, they must be referenced in the dependencies field of the plugin configuration. The operator will look for the plugin-deps directory and create the resources described in the files within this directory.

Plugin dependencies can be referenced in the dynamic-plugins' ConfigMap. This can either be part of the profile's default configuration for all Backstage CRs or part of the ConfigMap referenced in the Backstage CR. Starting from version 1.7, plugin dependencies can be included 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 will look for files in the plugin-deps directory whose names either start with the specified ref value or exactly match it. These files will be used to create the resources described within them.

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

In this example, both example-dep1.yaml and example-dep1.yaml will be picked and operator create the resources described in the files.

Same as other plugin configuration options, the dependencies can be defined in the default configuration for the profile or in the ConfigMap referenced in the Backstage CR. If a dependency is defined in both places, the operator will replace the one defined in the default configuration with the one defined in the Backstage CR. So if you want to define dependencies in CR, you need to redefine all of them in the CR, even if some of them are already defined in the default configuration. In a case if you want to clean up the dependencies defined in the default configuration, you can set dependencies: [] in the CR.

See also Orchestrator plugin dependencies as an example.