feat: support configuring multiple catalog index images [RHIDP-12935] (#2717)

* feat: support configuring multiple catalog index images

Currently the operator only supports a single catalog index image
(CATALOG_INDEX_IMAGE), which limits users who need to load plugin
configurations from multiple sources.

This adds support for a new EXTRA_CATALOG_INDEX_IMAGES env var on the
install-dynamic-plugins init container, accepting a comma-separated list
of entries in either name=image_ref or plain image_ref format.

For disconnected environments, RELATED_IMAGE_extra_catalog_index_{name}
env vars on the controller are collected at reconciliation time and
forwarded as EXTRA_CATALOG_INDEX_IMAGES using the name=image_ref format.
User-specified extraEnvs or deployment patches take precedence, matching
the existing CATALOG_INDEX_IMAGE behavior.

Ref: RHIDP-12935

Assisted-by: Claude

* Apply suggestions from code review

Co-authored-by: Armel Soro <armel@rm3l.org>

* fix: preserve env var declaration order in EXTRA_CATALOG_INDEX_IMAGES

The install-dynamic-plugins container processes extra catalog index
images in order, so sorting them alphabetically could change behavior.
Drop the sort and preserve the order in which the
RELATED_IMAGE_extra_catalog_index_* env vars are declared.

Ref: RHIDP-12935

Assisted-by: Claude

* chore: bump catalog index image to 1.10 and add community placeholder

Update RELATED_IMAGE_catalog_index to point to the 1.10 tag.
Add a commented-out RELATED_IMAGE_extra_catalog_index_community entry
for when a community catalog index image becomes available.

Ref: RHIDP-12935

Assisted-by: Claude

* docs: document RELATED_IMAGE_extra_catalog_index_* and clarify ordering

The order of entries in EXTRA_CATALOG_INDEX_IMAGES is determined by the
OS and not guaranteed. Update code comments, tests, and docs to reflect
this instead of claiming declaration order is preserved.

Assisted-by: Claude

* Apply suggestions from code review

Co-authored-by: Armel Soro <armel@rm3l.org>

* Apply suggestion from @rm3l

* refactor: remove RELATED_IMAGE_catalog_index and RELATED_IMAGE_extra_catalog_index handling

While listing related images in the CSV can serve as a bill of materials
of all images the operator needs (consumable by tools like oc-mirror or
security scanners), plugin catalog index images are a special case:
they are not pulled by the Kubelet but directly by skopeo from inside
the install-dynamic-plugins script. This means that in disconnected
environments, having them automatically mirrored by oc-mirror would not
work out of the box, since ImageContentSourcePolicy, ImageDigestMirrorSet
or ImageTagMirrorSet resources have no effect on skopeo pulls.

To avoid confusion, we rely on the separate plugin mirroring script and
docs for handling plugin and catalog index image mirroring.

Assisted-by: Claude

* fixup! refactor: remove RELATED_IMAGE_catalog_index and RELATED_IMAGE_extra_catalog_index handling

* docs: document catalog index image mirroring in disconnected environments

Assisted-by: Claude

* Apply suggestion from @rm3l

Author: rm3l

.rhdh/docs/mirror-dynamic-plugins.adoc

@@ -121,6 +121,17 @@ After mirroring completes, the script generates a `rhdh-plugin-mirroring-summary
 
 To use the mirrored plugins in RHDH, you need to configure container registry mirroring so that RHDH transparently pulls plugins from your mirror registry instead of the original source registries. This is done by mounting a custom `registries.conf` (and `policy.json` if needed) as extra files into the RHDH init container, as depicted in the sections below. See link:../../examples/plugin-mirroring.yaml[examples/plugin-mirroring.yaml] for a CR example.
 
+[#_catalog_index_image_mirroring]
+==== Catalog index image mirroring
+
+When `--plugin-index` is used, the script mirrors the plugin catalog index image itself in addition to the individual plugin artifacts. The mirrored location is included in the generated `rhdh-plugin-mirroring-summary.txt` file.
+
+If you configure transparent registry mirroring via `registries.conf` (as described in <<_creating_registry_mirroring_configmap>>), no additional RHDH configuration is needed -- the catalog index image will be pulled from the mirror automatically.
+
+Alternatively, you can explicitly point RHDH to the mirrored catalog index images by setting `CATALOG_INDEX_IMAGE` and/or `EXTRA_CATALOG_INDEX_IMAGES` environment variables on the `install-dynamic-plugins` init container (see link:../../docs/dynamic-plugins.md#extra-catalog-index-images[Extra catalog index images]). This can be done via `extraEnvs` in the Backstage CR (when using the RHDH Operator) or via `upstream.backstage.initContainers.env` in Helm values (when using the RHDH Helm chart). However, this should not be necessary when `registries.conf` is properly configured for transparent mirroring.
+
+NOTE: Unlike container images pulled by the Kubelet, plugin catalog index images are pulled directly by `skopeo` from inside the `install-dynamic-plugins` init container. This means that cluster-level mirroring resources (`ImageContentSourcePolicy`, `ImageDigestMirrorSet`, `ImageTagMirrorSet`) have no effect. You should use the `registries.conf`-based approach described here.
+
 [#_creating_registry_mirroring_configmap]
 ==== Creating the registry mirroring ConfigMap
 

bundle/backstage.io/manifests/backstage-operator.clusterserviceversion.yaml

@@ -68,7 +68,6 @@ spec:
               value: /opt/app-root/src/.npmrc.dynamic-plugins/.npmrc
             - name: MAX_ENTRY_SIZE
               value: "30000000"
-            # CATALOG_INDEX_IMAGE will be replaced by the value of the `RELATED_IMAGE_catalog_index` env var, if set
             - name: CATALOG_INDEX_IMAGE
               value: "quay.io/rhdh/plugin-catalog-index:1.9"
             - name: CATALOG_ENTITIES_EXTRACT_DIR

bundle/rhdh/manifests/backstage-operator.clusterserviceversion.yaml

@@ -28,8 +28,6 @@ spec:
               value: quay.io/fedora/postgresql-15:latest
             - name: RELATED_IMAGE_backstage
               value: quay.io/rhdh-community/rhdh:next
-            - name: RELATED_IMAGE_catalog_index
-              value: quay.io/rhdh/plugin-catalog-index:1.9
           volumeMounts:
             - mountPath: /default-config/flavours/lightspeed
               name: flavour-lightspeed-config

bundle/rhdh/manifests/rhdh-default-config_v1_configmap.yaml

@@ -50,6 +50,31 @@ The operator supports loading default plugin configurations from an OCI containe
 By default, the `rhdh` profile of operator [injects](../config/profile/rhdh/patches/deployment-patch.yaml#L31-L32) 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](../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](https://github.com/redhat-developer/rhdh/blob/main/docs/dynamic-plugins/installing-plugins.md#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:
+
+```yaml
+apiVersion: rhdh.redhat.com/v1alpha6
+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.

config/profile/rhdh/default-config/deployment.yaml

@@ -6,8 +6,15 @@ spec:
   application:
     extraEnvs:
       envs:
+        # Override the primary catalog index image
         - name: CATALOG_INDEX_IMAGE
           value: "quay.io/rhdh/plugin-catalog-index:1.9"
           containers:
             - install-dynamic-plugins
+        ## Optional: add extra catalog index images (comma-separated, supports name=image_ref or image_ref format).
+        # See https://github.com/redhat-developer/rhdh/blob/main/docs/dynamic-plugins/installing-plugins.md#using-extra-catalog-index-images for more details.
+        #- name: EXTRA_CATALOG_INDEX_IMAGES
+        #  value: "rhdh-community=quay.io/rhdh-community/plugin-catalog-index:1.10,internal=registry.example.com/rhdh-catalog:latest"
+        #  containers:
+        #  - install-dynamic-plugins
 

config/profile/rhdh/patches/deployment-patch.yaml

@@ -29,7 +29,6 @@ const (
 )
 
 const BackstageImageEnvVar = "RELATED_IMAGE_backstage"
-const CatalogIndexImageEnvVar = "RELATED_IMAGE_catalog_index"
 const DefaultMountDir = "/opt/app-root/src"
 const ExtConfigHashAnnotation = "rhdh.redhat.com/ext-config-hash"
 
@@ -107,13 +106,6 @@ func (b *BackstageDeployment) addToModel(model *BackstageModel, backstage api.Ba
 		b.setImage(ptr.To(os.Getenv(BackstageImageEnvVar)))
 	}
 
-	// Set CATALOG_INDEX_IMAGE from operator env var BEFORE extraEnvs are applied, so user-specified extraEnvs can still override this value
-	if catalogIndexImage := os.Getenv(CatalogIndexImageEnvVar); catalogIndexImage != "" {
-		if i, _ := DynamicPluginsInitContainer(b.podSpec().InitContainers); i >= 0 {
-			b.setOrAppendEnvVar(&b.podSpec().InitContainers[i], "CATALOG_INDEX_IMAGE", catalogIndexImage)
-		}
-	}
-
 	if err := b.setDeployment(backstage); err != nil {
 		return false, err
 	}