Configure the dynamic plugins cache

The dynamic plugins cache reduces platform boot time by storing already-installed plugins and skipping redundant downloads when the configuration does not change.

When you enable dynamic plugins cache:

  • The system calculates a checksum of each plugin’s YAML configuration (excluding pluginConfig).
  • The system stores the checksum in a file named dynamic-plugin-config.hash within the plugin’s directory.
  • During boot, if a plugin’s package reference matches the earlier installation and the checksum does not change, the system skips the download.
  • The system automatically removes plugins that you disabled since the earlier boot.
Note
To enable the dynamic plugins cache in RHDH, the plugins directory dynamic-plugins-root must be a persistent volume.

Create a persistent volume claim

Store already-installed dynamic plugins on a persistent volume to reduce Red Hat Developer Hub boot time and avoid redundant downloads.

The dynamic plugins cache reduces platform boot time by storing already-installed plugins and skipping redundant downloads when the configuration does not change.

When you enable the dynamic plugins cache:

  • The system calculates a checksum of each plugin's YAML configuration, excluding pluginConfig.
  • The system stores the checksum in a file named dynamic-plugin-config.hash within the plugin's directory.
  • During boot, if a plugin's package reference matches the earlier installation and the checksum has not changed, the system skips the download.
  • The system automatically removes plugins that you disabled since the earlier boot.
Note
To enable the dynamic plugins cache in Red Hat Developer Hub, the plugins directory dynamic-plugins-root must be a persistent volume. Use one of the following procedures to create the persistent volume claim (PVC) for your deployment type.

Create PVC with Operator

Create a persistent volume claim for the dynamic plugin cache in Operator deployments by replacing the default dynamic-plugins-root volume.

Before you begin

  • You have installed Red Hat Developer Hub on OpenShift Container Platform using the Red Hat Developer Hub Operator.
  • You have installed the OpenShift CLI (oc).

Procedure

  1. Create the persistent volume definition and save it to a file, such as pvc.yaml. For example:
    kind: PersistentVolumeClaim
    apiVersion: v1
    metadata:
      name: dynamic-plugins-root
    spec:
      accessModes:
        - ReadWriteOnce
      resources:
        requests:
          storage: 5Gi
    Note

    This example uses ReadWriteOnce as the access mode which prevents many replicas from sharing the PVC across different nodes. To run many replicas on different nodes, depending on your storage driver, you must use an access mode such as ReadWriteMany.

  2. To apply this PVC to your cluster, run the following command:
    $ oc apply -f pvc.yaml
  3. Replace the default dynamic-plugins-root volume with a PVC named dynamic-plugins-root. For example:
    apiVersion: rhdh.redhat.com/v1alpha5
    kind: Backstage
    metadata:
      name: developer-hub
    spec:
      deployment:
        patch:
          spec:
            template:
              spec:
                volumes:
                  - $patch: replace
                    name: dynamic-plugins-root
                    persistentVolumeClaim:
                      claimName: dynamic-plugins-root
    Note
    To avoid adding a new volume, you must use the $patch: replace directive.

Create PVC with Helm Chart

Create a persistent volume claim for the dynamic plugin cache in Helm deployments to persist the cache across pod restarts.

Before you begin

  • You have installed Red Hat Developer Hub using the Helm chart.
  • You have installed the OpenShift CLI (oc).

Procedure

  1. Create the persistent volume definition. For example:
    kind: PersistentVolumeClaim
    apiVersion: v1
    metadata:
      name: dynamic-plugins-root
    spec:
      accessModes:
        - ReadWriteOnce
      resources:
        requests:
          storage: 5Gi
    Note

    This example uses ReadWriteOnce as the access mode which prevents many replicas from sharing the PVC across different nodes. To run many replicas on different nodes, depending on your storage driver, you must use an access mode such as ReadWriteMany.

  2. To apply this PVC to your cluster, run the following command:
    $ oc apply -f pvc.yaml
  3. Configure the Helm chart to use the PVC by setting the dynamicPlugins.volume.type field to pvc and referencing the claim name:
    dynamicPlugins:
      volume:
        type: "pvc"
        pvc:
          claimName: dynamic-plugins-root
    Note

    The Helm chart mounts the dynamic plugins directory automatically. You do not need to define extraVolumes or extraVolumeMounts entries for the cache.

Resolve plugin configuration errors

Fix temporary 404 errors caused by inconsistent dynamic plugins cache states across Red Hat Developer Hub replicas.

Before you begin

Your API version is v1alpha5 or later.

About this task

When multiple Red Hat Developer Hub replicas share a single dynamic plugins cache persistent volume claim (PVC), updating the configuration through the Operator can trigger temporary 404 errors. This happens because replicas can read inconsistent cache states before all replicas finish synchronizing. Using an individual cache per pod resolves this issue.

Procedure

  1. In the Backstage custom resource (CR) file, set spec.deployment to use StatefulSet as the resource kind.
    apiVersion: rhdh.redhat.com/v1alpha5
    kind: Backstage
    metadata:
      name: <CR_name>
    spec:
     deployment:
      kind: StatefulSet
      patch:
       spec:
         replicas: 2
         template:
           spec:
             volumes:
               - $patch: replace
                 name: dynamic-plugins-root
                 persistentVolumeClaim:
                   claimName: dynamic-plugins-root
         volumeClaimTemplates:
           - apiVersion: v1
             kind: PersistentVolumeClaim
             metadata:
               name: dynamic-plugins-root
             spec:
               accessModes:
                 - ReadWriteOnce
               resources:
                 requests:
                   storage: 1Gi
    Note
    Using StatefulSet with a single replica can cause downtime while the application deletes the old pod and creates a new one.
  2. Wait a few minutes until the Operator reconciles the CR and the StatefulSet resource is ready.
  3. If you are updating an existing CR, remove the earlier Deployment resource from the cluster.
    oc delete deployment -l app.kubernetes.io/instance=<CR_name>
    Note
    The same requirement applies when changing the resource kind from StatefulSet back to Deployment. You must manually delete the previously created resource from the cluster, because the Operator does not automatically remove the legacy resource.

Set dynamic plugin cache pull policy

Set the pull policy and download parameters for the dynamic plugins cache in the dynamic-plugins.yaml file.

Procedure

In your dynamic-plugins.yaml file, set the optional dynamic plugin cache parameters:
pullPolicy: IfNotPresent (default)
Downloads the artifact only if it is not already present in the dynamic-plugins-root folder, without checking image digests.
pullPolicy: Always
Compares the image digest in the remote registry and downloads the artifact if it has changed, even if Red Hat Developer Hub already downloaded the plugin. When applied to the NPM download method, downloads the remote artifact without a digest check.
forceDownload: false (default)
Older option that downloads the artifact only if it is not already present in the dynamic-plugins-root folder, without checking image digests.
forceDownload: true
Older option that forces a reinstall of the plugin, bypassing the cache.

Example configuration to download a remote artifact without a digest check, using pullPolicy: Always:

plugins:
  - disabled: false
    pullPolicy: Always
    package: 'oci://quay.io/example-org/example-plugin:v1.0.0'
Note
pullPolicy takes precedence over forceDownload. The forceDownload option may become deprecated in a future Red Hat Developer Hub release.