Skip to content

[release-1.9-post-cqa] [RHDHBUGS-2802]: Remove !<plugin-name> suffixes from OCI artifact paths #1994

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
themr0c merged 1 commit into from
Apr 1, 2026
Merged

[release-1.9-post-cqa] [RHDHBUGS-2802]: Remove !<plugin-name> suffixes from OCI artifact paths #1994

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .../assembly-install-plugins-from-oci-registries-by-using-custom-certificates.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ includes:

plugins:
- disabled: false
package: oci://reg.example.com:5000/myplugin:v0.0.1!backstage-plugin-myplugin
package: oci://reg.example.com:5000/myplugin:v0.0.1
----

== Prerequisites
Expand Down
2 changes: 1 addition & 1 deletion modules/configure_configuring-rhdh/proc-configure-the-dynamic-plugins-cache.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ Example `dynamic-plugins.yaml` file configuration to download the remote artifac
plugins:
- disabled: false
pullPolicy: Always
package: 'oci://quay.io/example-org/example-plugin:v1.0.0!internal-backstage-plugin-example'
package: 'oci://quay.io/example-org/example-plugin:v1.0.0'
----

`forceDownload: false` (default)::
Expand Down
4 changes: 2 additions & 2 deletions modules/extend_dynamic-plugins-reference/rhdh-supported-plugins.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -641,9 +641,9 @@ generate_migration_table() {
old_path="./dynamic-plugins/dist/${plugin_name}"

# Extract new path - get the base URL without the version/integrity part
# Format: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/backstage-community-plugin-jenkins:bs_1.45.3__0.26.0!backstage-community-plugin-jenkins
# Format: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/backstage-community-plugin-jenkins:bs_1.45.3__0.26.0
# We want: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/backstage-community-plugin-jenkins:<tag>
# First remove everything after the ! (integrity hash), then remove the tag to get base
# Remove the tag to get the base path
artifact_without_hash="${dynamic_artifact%%!*}"
new_path_base="${artifact_without_hash%:*}"
new_path="${new_path_base}:<tag>"
Expand Down
4 changes: 2 additions & 2 deletions ...ating-ai-development-with-openshift-ai-connector-for-rhdh/proc-set-up-with.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -168,9 +168,9 @@ The {product-very-short} Pod requires two dynamic plugins.
----
plugins:
- disabled: false
package: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-catalog-backend-module-model-catalog:bs_1.42.5__0.7.0!red-hat-developer-hub-backstage-plugin-catalog-backend-module-model-catalog
package: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-catalog-backend-module-model-catalog:bs_1.42.5__0.7.0
- disabled: false
package: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-catalog-techdoc-url-reader-backend:bs_1.42.5__0.3.0!red-hat-developer-hub-backstage-plugin-catalog-techdoc-url-reader-backend
package: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-catalog-techdoc-url-reader-backend:bs_1.42.5__0.3.0
----

. Add the `Connector` sidecar containers to the {product-very-short} Pod.
Expand Down
10 changes: 5 additions & 5 deletions ...protocol-tools-for-rhdh/proc-verify-successful-installation-of-mcp-plugins.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,16 +28,16 @@ $ oc logs -c install-dynamic-plugins deployment/<my-product-deployment>
[source]
----
..... prior logs ....
======= Installing dynamic plugin oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/backstage-plugin-mcp-actions-backend:bs_1.42.5__0.1.2!backstage-plugin-mcp-actions-backend
======= Installing dynamic plugin oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/backstage-plugin-mcp-actions-backend:bs_1.42.5__0.1.2
==> Copying image oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/backstage-plugin-mcp-actions-backend:next__0.2.0 to local filesystem
==> Successfully installed dynamic plugin oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/backstage-plugin-mcp-actions-backend:bs_1.42.5__0.1.2!backstage-plugin-mcp-actions-backend
==> Successfully installed dynamic plugin oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/backstage-plugin-mcp-actions-backend:bs_1.42.5__0.1.2
----
. You must see entries for any of the MCP tool plugins you installed as shown in the following code:
+
[source]
----
..... prior logs ....
======= Installing dynamic plugin oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-software-catalog-mcp-tool:bs_1.42.5__0.2.3!red-hat-developer-hub-backstage-plugin-software-catalog-mcp-tool
==> Copying image oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-software-catalog-mcp-tool:bs_1.42.5__0.2.3!red-hat-developer-hub-backstage-plugin-software-catalog-mcp-tool to local filesystem
==> Successfully installed dynamic plugin oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-software-catalog-mcp-tool:bs_1.42.5__0.2.3!red-hat-developer-hub-backstage-plugin-software-catalog-mcp-tool
======= Installing dynamic plugin oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-software-catalog-mcp-tool:bs_1.42.5__0.2.3
==> Copying image oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-software-catalog-mcp-tool:bs_1.42.5__0.2.3 to local filesystem
==> Successfully installed dynamic plugin oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-software-catalog-mcp-tool:bs_1.42.5__0.2.3
----
2 changes: 1 addition & 1 deletion ...ing-scorecards/proc-configure-portfolio-health-on-a-customizable-home-page.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ You can add the aggregated Scorecard widget to a customizable {product-very-shor
[source,yaml]
----
plugins:
- package: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-scorecard:bs_1.45.3__2.3.5!red-hat-developer-hub-backstage-plugin-scorecard
- package: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-scorecard:bs_1.45.3__2.3.5
disabled: false
pluginConfig:
dynamicPlugins:
Expand Down
2 changes: 1 addition & 1 deletion ...-using-scorecards/proc-configure-portfolio-health-on-a-read-only-home-page.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ You can add the aggregated Scorecard widget to a read-only {product-very-short}
[source,yaml]
----
plugins:
- package: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-scorecard:bs_1.45.3__2.3.5!red-hat-developer-hub-backstage-plugin-scorecard
- package: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-scorecard:bs_1.45.3__2.3.5
disabled: false
pluginConfig:
dynamicPlugins:
Expand Down
4 changes: 2 additions & 2 deletions ...ervability_evaluate-project-health-using-scorecards/proc-enable-scorecards.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ To monitor component health and quality in {product-very-short}, you must enable
[source,yaml]
----
plugins:
- package: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-scorecard:bs_1.45.3__2.3.5!red-hat-developer-hub-backstage-plugin-scorecard
- package: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-scorecard:bs_1.45.3__2.3.5
disabled: false
pluginConfig:
dynamicPlugins:
Expand All @@ -36,6 +36,6 @@ plugins:
if:
allOf:
- isKind: component
- package: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-scorecard-backend:bs_1.45.3__2.3.5!red-hat-developer-hub-backstage-plugin-scorecard-backend
- package: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-scorecard-backend:bs_1.45.3__2.3.5
disabled: false
----
2 changes: 1 addition & 1 deletion ...lth-using-scorecards/proc-integrate-github-health-metrics-using-scorecards.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -88,7 +88,7 @@ integrations:
[source,yaml]
----
plugins:
- package: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-scorecard-backend-module-github:bs_1.45.3__2.3.5!red-hat-developer-hub-backstage-plugin-scorecard-backend-module-github
- package: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-scorecard-backend-module-github:bs_1.45.3__2.3.5
disabled: false
----

Expand Down
4 changes: 2 additions & 2 deletions ...ealth-using-scorecards/proc-integrate-jira-health-metrics-using-scorecards.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ You must use the proxy setup to ensure configuration compatibility if you also u
[source,yaml]
----
plugins:
- package: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-scorecard-backend-module-jira:bs_1.45.3__2.3.5!red-hat-developer-hub-backstage-plugin-scorecard-backend-module-jira
- package: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-scorecard-backend-module-jira:bs_1.45.3__2.3.5
disabled: false
----
... In your {product-very-short} `{my-app-config-file}` file, add the following direct setup settings:
Expand All @@ -67,7 +67,7 @@ where:
[source,yaml]
----
plugins:
- package: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-scorecard-backend-module-jira:bs_1.45.3__2.3.5!red-hat-developer-hub-backstage-plugin-scorecard-backend-module-jira
- package: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-scorecard-backend-module-jira:bs_1.45.3__2.3.5
disabled: false
----

Expand Down
2 changes: 1 addition & 1 deletion modules/shared/con-dynamic-plugins.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ With dynamic plugins, instead of modifying the {backstage} application itself, y
[source,yaml]
----
plugins:
- package: oci://quay.io/account-name/image-name:tag!plugin-name
- package: oci://quay.io/account-name/image-name:tag
disabled: false
pluginConfig: {}
----
4 changes: 2 additions & 2 deletions modules/shared/proc-add-a-custom-dynamic-plugin-to-rhdh.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,9 +12,9 @@ Use this procedure to add custom dynamic plugins to {product} by updating the dy
[source,yaml]
----
plugins:
- package: oci://quay.io/_<user_name>_/entity-feedback-plugin:0.5.0!backstage-community-plugin-entity-feedback
- package: oci://quay.io/_<user_name>_/entity-feedback-plugin:0.5.0
disabled: false
- package: oci://quay.io/_<user_name>_/entity-feedback-plugin-backend:0.6.0!backstage-community-plugin-entity-feedback-backend
- package: oci://quay.io/_<user_name>_/entity-feedback-plugin-backend:0.6.0
disabled: false
----
+
Expand Down
4 changes: 2 additions & 2 deletions modules/shared/proc-add-a-dynamic-plugin-to-rhdh.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ To add a custom dynamic plugin to {product}, update the `dynamic-plugins.yaml` f
[source,yaml,subs="+attributes,+quotes"]
----
plugins:
- package: oci://quay.io/_<account-name>_/_<image-name>_:_<tag>_!_<plugin-name>_
- package: oci://quay.io/_<account-name>_/_<image-name>_:_<tag>_
disabled: false
pluginConfig: {}
----
Expand All @@ -29,7 +29,7 @@ The following example integrates a plugin named `simple-example` with {product-v
----
plugins:
# Option 1: Load from an OCI image
- package: oci://quay.io/<namespace>/simple-example:v0.1.0!backstage-plugin-simple-example
- package: oci://quay.io/<namespace>/simple-example:v0.1.0
disabled: false
pluginConfig:
dynamicPlugins:
Expand Down
2 changes: 1 addition & 1 deletion modules/shared/proc-configure-front-end-plugin-wiring.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ This configuration determines how the plugin is integrated with the {product-ver
----
plugins:
# Option 1: Load from an OCI image
- package: oci://quay.io/<namespace>/simple-example:v0.1.0!backstage-plugin-simple-example
- package: oci://quay.io/<namespace>/simple-example:v0.1.0
disabled: false
pluginConfig:
dynamicPlugins:
Expand Down
2 changes: 1 addition & 1 deletion modules/shared/proc-display-the-front-end-plugin.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ Use this procedure to configure and display a front-end plugin in the {product}
.`dynamic-plugins.yaml` file fragment
[source,yaml]
----
- package: oci://quay.io/_<user_name>_/entity-feedback-plugin:0.5.0!backstage-community-plugin-entity-feedback
- package: oci://quay.io/_<user_name>_/entity-feedback-plugin:0.5.0
disabled: false
pluginConfig:
dynamicPlugins:
Expand Down
2 changes: 1 addition & 1 deletion modules/shared/proc-install-and-configure-a-third-party-techdocs-add-on.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -61,7 +61,7 @@ $ docker push quay.io/_<user_name>_/_<techdocs_add-on_image>_:latest
[source,yaml,subs="+quotes,+attributes"]
----
plugins:
- package: oci://quay.io/_<user_name>_/_<techdocs_add-on_image>_:latest!_<techdocs_add-on_package>_
- package: oci://quay.io/_<user_name>_/_<techdocs_add-on_image>_:latest
disabled: false
pluginConfig:
dynamicPlugins:
Expand Down
53 changes: 7 additions & 46 deletions modules/shared/proc-load-a-plugin-packaged-as-an-oci-image.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,29 +37,7 @@ oc create secret generic _<secret_name>_ --from-file=auth.json=${XDG_RUNTIME_DIR

. Define the plugin with the `oci://` prefix by using one of the following formats in your `dynamic-plugins.yaml` file:

Standard explicit definition:: Use the format `oci://<image_name>:<tag>!<plugin_path>`, as shown in the following example:
+
Example configuration in `dynamic-plugins.yaml` file:
+
[source,yaml]
----
plugins:
- disabled: false
package: oci://quay.io/example/image:v0.0.1!backstage-plugin-myplugin
----

Using image digests:: 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:
+
[source,yaml]
----
plugins:
- disabled: false
package: oci://quay.io/example/image@sha256:28036abec4dffc714394e4ee433f16a59493db8017795049c831be41c02eb5dc!backstage-plugin-myplugin
----

Using path auto-detection:: If the OCI image has only a single plugin, you can omit the path after the exclamation point. The installation program automatically extracts the path from the image metadata, as shown in the following example:
Standard definition:: Use the format `oci://<image_name>:<tag>`, as shown in the following example. The installation program automatically extracts the plugin path from the image metadata.
+
Example configuration in `dynamic-plugins.yaml` file:
+
Expand All @@ -73,39 +51,22 @@ plugins:
[NOTE]
====
You must package images with the `@red-hat-developer-hub/cli` to ensure the system applies the `io.backstage.dynamic-packages` annotation.

You must define exactly one plugin from that OCI image in the configuration files. The system returns an error if the configuration files contain many plugins or no matching plugins.
====

Using version inheritance:: To inherit a version from a base configuration file, for example, `dynamic-plugins.default.yaml`, use the `{{inherit}}` placeholder to inherit the `v0.0.2` tag, as shown in the following example:
+
Example configuration in `dynamic-plugins.default.yaml` file:
+
[default-source,yaml]
----
plugins:
- disabled: false
package: oci://quay.io/example/image:v0.0.2!backstage-plugin-myplugin
----
Using image digests:: 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:
+
[source,yaml]
----
includes:
- dynamic-plugins.default.yaml
plugins:
- disabled: false
package: oci://quay.io/example/image:{{inherit}}!backstage-plugin-myplugin
package: oci://quay.io/example/image@sha256:28036abec4dffc714394e4ee433f16a59493db8017795049c831be41c02eb5dc
----
+
[NOTE]
====
An error occurs if you use `{{inherit}}` in the includes file itself or if no matching plugin key exists in the base configuration.
====

Combining version inheritance with path omission::
When using `{{inherit}}` for version inheritance, you can also use the plugin path auto-detection feature by omitting the plugin path entirely. Use this approach when the base configuration in included files already has an explicit path or uses auto-detection itself.
+
For example, if the plugin in the included file uses auto-detection that resolves to `oci://quay.io/example/image:v0.0.2!example-path`, and you use `{{inherit}}` without a path, it will inherit both the version `v0.0.2` and the plugin path `example-path`.
Using version inheritance:: To inherit a version from a base configuration file, for example, `dynamic-plugins.default.yaml`, use the `{{inherit}}` placeholder to inherit the `v0.0.2` tag, as shown in the following example:
+
Example configuration in `dynamic-plugins.default.yaml` file:
+
Expand All @@ -129,7 +90,7 @@ plugins:
+
[NOTE]
====
You must define exactly one plugin from that OCI image in the configuration files. The system returns an error if the configuration files contain many plugins or no matching plugins.
An error occurs if you use `{{inherit}}` in the includes file itself or if no matching plugin key exists in the base configuration.
====

. To apply the changes, restart the {product-very-short} application.
6 changes: 3 additions & 3 deletions modules/shared/proc-mirror-plugins-from-a-file.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,9 +13,9 @@ Example `plugins.txt` file:
+
[source,text]
----
oci://quay.io/rhdh-plugin-catalog/backstage-community-plugin-quay:1.8.0--1.22.1!backstage-community-plugin-quay
oci://quay.io/rhdh-plugin-catalog/backstage-community-plugin-github-actions:1.8.0--0.11.1!backstage-community-plugin-github-actions
oci://quay.io/rhdh-plugin-catalog/backstage-community-plugin-azure-devops:1.8.0--0.8.2!backstage-community-plugin-azure-devops
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
----
. Download the mirroring script:
+
Expand Down
11 changes: 3 additions & 8 deletions modules/shared/proc-mirror-specific-plugins-by-direct-reference.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,14 +20,9 @@ For example:
[source,terminal,subs="+quotes,+attributes"]
----
bash mirror-plugins.sh \
--plugins 'oci://quay.io/rhdh-plugin-catalog/backstage-community-plugin-quay:1.8.0--1.22.1!backstage-community-plugin-quay' \
'oci://quay.io/rhdh-plugin-catalog/backstage-community-plugin-github-actions:1.8.0--0.11.1!backstage-community-plugin-github-actions' \
--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.
+
[NOTE]
====
You must quote plugin URLs that contain an OCI subpath (`!`) to prevent shell interpretation.
====
`--to-registry _<my.registry.example.com>_`:: Enter the URL for the target mirror registry where you want to mirror the catalog index.
Loading