RHIDP-12610 - Support several plugin catalogs in the Extensions plugin - #2579
RHIDP-12610 - Support several plugin catalogs in the Extensions plugin#2579Gerry-Forde wants to merge 5 commits into
Conversation
PR Build ResultsBuild passed -- 36/36 titles | 93s Content Quality AssessmentCQA Report
SummaryChecks: 22 total, 22 pass, 0 fail Modules not yet in product_product15 modules (proc, con, ref) are not yet included in the
|
|
Gerry-Forde
added
Technical review needed 🔩
| * Catalog entities for the Extensions UI | ||
| * The `dynamic-plugins.default.yaml` file with out-of-the-box plugin configurations | ||
|
|
||
| When you deploy {product}, plugins listed in the primary catalog's `dynamic-plugins.default.yaml` install automatically. This ensures a consistent baseline plugin ecosystem across {product} installations. |
There was a problem hiding this comment.
For clarity, they will only be installed automatically if they are enabled by default in dynamic-plugins.default.yaml. Otherwise, they won't be installed automatically even if they are listed in the primary catalog's dynamic-plugins.default.yaml file.
| If a catalog index image does not contain a `catalog-entities/` directory at the root level, {product} checks the following fallback locations in order: | ||
|
|
||
| . `marketplace/` | ||
| . `extensions/` |
There was a problem hiding this comment.
I don't think this is accurate. It checks catalog-entities/extensions and catalog-entities/marketplace in this order. These are subdirs within catalog-entities, not root-level dirs. And if there is no catalog-entities/, it just logs a warning message.
See https://github.com/redhat-developer/rhdh-plugins/blob/0ec0b3f4b23ba8ca1dc951c84ee9711cedb2cbee/workspaces/install-dynamic-plugins/packages/install-dynamic-plugins/src/catalog-index.ts#L62-L65 and https://github.com/redhat-developer/rhdh-plugins/blob/0ec0b3f4b23ba8ca1dc951c84ee9711cedb2cbee/workspaces/install-dynamic-plugins/packages/install-dynamic-plugins/src/catalog-index.ts#L224-L230
| In disconnected or air-gapped environments using the Operator, you must configure matching `RELATED_IMAGE_extra_catalog_index_<name>` environment variables on the Operator controller. | ||
| The `<name>` portion of the `RELATED_IMAGE` variable must match the subdirectory name used in `EXTRA_CATALOG_INDEX_IMAGES`. | ||
|
|
||
| Example: | ||
|
|
||
| [source,yaml] | ||
| ---- | ||
| # Operator deployment | ||
| env: | ||
| - name: RELATED_IMAGE_extra_catalog_index_community | ||
| value: internal-registry.example.com/community/catalog:v1.10 |
There was a problem hiding this comment.
We pushed back on this approach, so not accurate. The procedure for mirroring a catalog index image is already here and involves calling the mirroring script: https://docs.redhat.com/en/documentation/red_hat_developer_hub/1.10/html-single/installing_and_viewing_plugins_in_red_hat_developer_hub/index#catalog-index-image-mirroring_deploy-rhdh-with-mirrored-plugins-in-a-disconnected-environment
| |`tag` | ||
| |String | ||
| |Yes | ||
| |The image tag (for example, `v1.10.0`, `latest`, `sha256:abc123`). |
There was a problem hiding this comment.
| |The image tag (for example, `v1.10.0`, `latest`, `sha256:abc123`). | |
| |The image tag (for example, `v1.10.0`, `latest`). |
sha256:abc123 is a digest actually.
| [id="extra-catalog-index-directory-structure_{context}"] | ||
| = Extra catalog index directory structure reference | ||
|
|
||
| [role="_abstract"] | ||
| {product} extracts catalog index images into a structured directory tree under `/extensions/`. Understanding this structure helps you verify and troubleshoot catalog extraction and configuration issues. | ||
|
|
||
| [id="primary-catalog-directory-structure_{context}"] | ||
| == Primary catalog directory structure | ||
|
|
||
| The primary catalog index image (configured via `CATALOG_INDEX_IMAGE`) is extracted to `/extensions/`: | ||
|
|
||
| ---- | ||
| /extensions/ | ||
| ├── catalog-entities/ # Plugin metadata for Extensions UI | ||
| └── dynamic-plugins.default.yaml # Default plugin configurations | ||
| ---- | ||
|
|
||
| The `catalog-entities/` directory contains Backstage software catalog descriptor files in YAML or JSON format. | ||
| The Extensions UI reads these files to display available plugins. | ||
|
|
||
| The `dynamic-plugins.default.yaml` file contains default plugin configurations. | ||
| {product} applies these configurations automatically during installation. | ||
|
|
||
| [id="extra-catalog-directory-structure_{context}"] | ||
| == Extra catalog directory structure | ||
|
|
||
| Each extra catalog index image (configured via `EXTRA_CATALOG_INDEX_IMAGES`) is extracted to `/extensions/extra/<subdirectory>/`: | ||
|
|
||
| ---- | ||
| /extensions/ | ||
| ├── catalog-entities/ # From CATALOG_INDEX_IMAGE | ||
| ├── dynamic-plugins.default.yaml # From CATALOG_INDEX_IMAGE | ||
| └── extra/ | ||
| ├── community/ | ||
| │ └── catalog-entities/ # From extra catalog "community" | ||
| ├── partner/ | ||
| │ └── catalog-entities/ # From extra catalog "partner" | ||
| └── internal/ | ||
| └── catalog-entities/ # From extra catalog "internal" | ||
| ---- | ||
|
|
||
| In this example: | ||
|
|
||
| * The `community/` subdirectory contains catalog entities from an extra catalog configured with the name `community`. | ||
| * The `partner/` subdirectory contains catalog entities from an extra catalog configured with the name `partner`. | ||
| * The `internal/` subdirectory contains catalog entities from an extra catalog configured with the name `internal`. | ||
|
|
||
| Each subdirectory contains only `catalog-entities/`. | ||
| Extra catalog index images do not provide `dynamic-plugins.default.yaml`. | ||
|
|
||
| [id="subdirectory-naming-rules_{context}"] | ||
| == Subdirectory naming rules | ||
|
|
||
| The subdirectory name under `/extensions/extra/` is determined by: | ||
|
|
||
| Explicit name:: When you configure an extra catalog using the `name=image_ref` format, the subdirectory name is the `<name>` portion. | ||
| + | ||
| Example: `community=quay.io/community/plugins:v1.10` creates `/extensions/extra/community/`. | ||
|
|
||
| Auto-derived name:: When you configure an extra catalog using the plain `image_ref` format, {product} derives the subdirectory name from the image reference by replacing `/`, `:`, and `@` characters with underscores (`_`). | ||
| + | ||
| Example: `quay.io/community/plugins:v1.10` creates `/extensions/extra/quay.io_community_plugins_v1.10/`. | ||
|
|
||
| [id="directory-structure-examples_{context}"] | ||
| == Directory structure examples | ||
|
|
||
| Single extra catalog with explicit name: | ||
|
|
||
| Configuration: `EXTRA_CATALOG_INDEX_IMAGES="community=quay.io/community/rhdh-plugin-catalog:v1.10.0"` | ||
|
|
||
| Resulting directory structure: | ||
|
|
||
| ---- | ||
| /extensions/ | ||
| ├── catalog-entities/ | ||
| ├── dynamic-plugins.default.yaml | ||
| └── extra/ | ||
| └── community/ | ||
| └── catalog-entities/ | ||
| ├── plugin-a.yaml | ||
| ├── plugin-b.yaml | ||
| └── plugin-c.yaml | ||
| ---- | ||
|
|
||
| Multiple extra catalogs with mixed naming: | ||
|
|
||
| Configuration: `EXTRA_CATALOG_INDEX_IMAGES="community=quay.io/community/plugins:v1.10,quay.io/partner/catalog:latest,internal=registry.example.com/custom:v2.0"` | ||
|
|
||
| Resulting directory structure: | ||
|
|
||
| ---- | ||
| /extensions/ | ||
| ├── catalog-entities/ | ||
| ├── dynamic-plugins.default.yaml | ||
| └── extra/ | ||
| ├── community/ | ||
| │ └── catalog-entities/ | ||
| ├── quay.io_partner_catalog_latest/ | ||
| │ └── catalog-entities/ | ||
| └── internal/ | ||
| └── catalog-entities/ | ||
| ---- | ||
|
|
||
| In this example: | ||
|
|
||
| * `community` and `internal` use explicit names. | ||
| * `quay.io_partner_catalog_latest` is auto-derived from the image reference `quay.io/partner/catalog:latest`. | ||
|
|
||
| Auto-derived names with complex image references: | ||
|
|
||
| Configuration: `EXTRA_CATALOG_INDEX_IMAGES="registry.example.com/team/plugins:v1.10.0,quay.io/org/catalog@sha256:abc123"` | ||
|
|
||
| Resulting directory structure: | ||
|
|
||
| ---- | ||
| /extensions/ | ||
| ├── catalog-entities/ | ||
| ├── dynamic-plugins.default.yaml | ||
| └── extra/ | ||
| ├── registry.example.com_team_plugins_v1.10.0/ | ||
| │ └── catalog-entities/ | ||
| └── quay.io_org_catalog_sha256_abc123/ | ||
| └── catalog-entities/ | ||
| ---- | ||
|
|
||
| Auto-derived names can become unwieldy with complex image references. | ||
| For production deployments, explicit naming is recommended. |
There was a problem hiding this comment.
Should all this be documented at all? It sounds like internal implementation detail on how we extract the different extra catalog index images, but nothing IMO really impacting the customer, no? We are doing this so all extra index images are extracted to unique folders, so that plugins can correctly be discovered by the Extensions backend. If later we decide to change the extraction pattern, the documentation here would be stale.
Just the last recommendation on explicit naming seems important from the end-user's standpoint. The rest is internal detail IMO. WDYT?
3 participants
IMPORTANT: Do Not Merge - To be merged by Docs Team Only
Version(s):
2.1
Issue:
RHIDP-12610
Preview:
Manage plugin catalog sources