Skip to content

docs: simplify plugin URL references, link to shared docs #3309

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

Open
jonkoops wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: simplify plugin URL references, link to shared docs #3309

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
33 changes: 2 additions & 31 deletions docs/dynamic-plugins.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -97,38 +97,9 @@ More details in [Catalog Entities Extraction](https://github.com/redhat-develope

## 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.
For full documentation and examples, see [Plugin References](https://github.com/redhat-developer/rhdh/blob/main/docs/dynamic-plugins/installing-plugins.md#plugin-references).

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.

```yaml
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.

```yaml
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 v2.0.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](https://github.com/redhat-developer/rhdh/blob/main/docs/dynamic-plugins/installing-plugins.md#oci-package-version-inheritance) which documents the RHDH init-container behavior (full URL matching).
**Operator-specific 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.

## Dynamic plugins dependency management

Expand Down