|
1 | | -# Plugins are manually created |
| 1 | +# Creating & Editing Extension Catalog Plugins |
2 | 2 |
|
3 | | -# Packages are generated with |
| 3 | +Spreadsheet for tracking the work is here: https://docs.google.com/spreadsheets/d/1K_LqKYma9nRM5teKD-uCnbB3qKC8Hk2E5jvcpMSfjTs/edit?gid=771893283#gid=771893283 |
4 | 4 |
|
| 5 | +## Working with Plugin Folders & Files |
| 6 | + |
| 7 | +Below are some practical instructions that might help you in the process of creating and updating plugins and packages for use in the RHDH Extensions catalog plugin. |
| 8 | + |
| 9 | +## `packages/` |
| 10 | + |
| 11 | +Packages describe the frontend and backend packages that form part of a plugin. The packages folder contains the individual `package.yaml` files where you can set various details about your plugin packages. For an example, see the 3scale package details in `packages/backstage-community-plugin-3scale-backend.yaml` |
| 12 | + |
| 13 | +```yaml |
| 14 | +apiVersion: extensions.backstage.io/v1alpha1 |
| 15 | +kind: Package # Important to set the kind |
| 16 | +metadata: |
| 17 | + name: backstage-community-plugin-3scale-backend # This name is important - it provides a linkage from the plugin record |
| 18 | + namespace: rhdh # This plugin package is built by us and provided in RHDH |
| 19 | + title: "@backstage-community/plugin-3scale-backend" |
| 20 | + links: # Links to useful sources etc. |
| 21 | + - url: https://red.ht/rhdh |
| 22 | + title: Homepage |
| 23 | + - url: https://issues.redhat.com/browse/RHIDP |
| 24 | + title: Bugs |
| 25 | + - title: Source Code |
| 26 | + url: https://github.com/redhat-developer/rhdh/tree/main/dynamic-plugins/wrappers/backstage-community-plugin-3scale-backend-dynamic |
| 27 | + annotations: # Activates backstage features |
| 28 | + backstage.io/source-location: url |
| 29 | + https://github.com/redhat-developer/rhdh/tree/main/dynamic-plugins/wrappers/backstage-community-plugin-3scale-backend-dynamic |
| 30 | + tags: [] |
| 31 | +spec: # Custom information processed by the Extensions plugin |
| 32 | + packageName: "@backstage-community/plugin-3scale-backend" |
| 33 | + dynamicArtifact: ./dynamic-plugins/dist/backstage-community-plugin-3scale-backend-dynamic |
| 34 | + version: 3.2.0 # The plugin version |
| 35 | + backstage: |
| 36 | + role: backend-plugin |
| 37 | + supportedVersions: 1.35.1 # The supported version of Backstage |
| 38 | + author: Red Hat # The Author of the package |
| 39 | + support: tech-preview # The release status of the package |
| 40 | + lifecycle: active # The backstage lifecycle stage |
| 41 | + partOf: |
| 42 | + - backstage-community-plugin-3scale-backend # Links this package to others in the same group |
| 43 | + appConfigExamples: # Information on how to configure the plugin (not used yet) |
| 44 | + - title: Default configuration |
| 45 | + content: |
| 46 | + catalog: |
| 47 | + providers: |
| 48 | + threeScaleApiEntity: |
| 49 | + default: |
| 50 | + baseUrl: ${THREESCALE_BASE_URL} |
| 51 | + accessToken: ${THREESCALE_ACCESS_TOKEN} |
| 52 | +``` |
| 53 | +
|
| 54 | +
|
| 55 | +## `packages/all.yaml` |
| 56 | + |
| 57 | +You **must** add your package yaml file to the list in the `packages/all.yaml` file to get it picked up by RHDH and loaded into the catalog. To check if it's loading, check the catalog. |
| 58 | + |
| 59 | +## `plugins/` |
| 60 | + |
| 61 | +The files in the `plugins` folder describe the plugins themselves. The plugins folder contains the individual `plugin.yaml` files where you can set various details about your plugin - many of which appear on screen in RHDH in the "Extensions" catalog tab. For an example, see the 3scale package details in `plugins/3scale.yaml`. |
| 62 | + |
| 63 | +```yaml |
| 64 | +# yaml-language-server: $schema=https://raw.githubusercontent.com/redhat-developer/rhdh-plugins/refs/heads/main/workspaces/marketplace/json-schema/plugins.json |
| 65 | +apiVersion: extensions.backstage.io/v1alpha1 |
| 66 | +kind: Plugin # Important to set the kind |
| 67 | +metadata: |
| 68 | + name: 3scale # The catalog entity name |
| 69 | + namespace: rhdh # This plugin is built by us and provided in RHDH |
| 70 | + title: 3scale |
| 71 | + annotations: |
| 72 | + extensions.backstage.io/pre-installed: 'true' # Not used, but would tell us if the plugin were pre-instralled |
| 73 | + extensions.backstage.io/verified-by: Red Hat # Set the verified status |
| 74 | + # extensions.backstage.io/certified-by: Red Hat # Set the certified status |
| 75 | + links: # Useful links for the plugin card when expanded |
| 76 | + - url: https://red.ht/rhdh |
| 77 | + title: Homepage |
| 78 | + - url: https://issues.redhat.com/browse/RHIDP |
| 79 | + title: Bugs |
| 80 | + - title: Source Code |
| 81 | + url: https://github.com/redhat-developer/rhdh/tree/main/dynamic-plugins/wrappers/backstage-community-plugin-3scale-backend-dynamic |
| 82 | + tags: |
| 83 | + - apis |
| 84 | + # The description below is used in the Extension plugin's "Tile" view as the plugin description. Keep it to a few lines (short description) |
| 85 | + description: | |
| 86 | + 3scale provides a comprehensive API management solution, enabling organizations to secure, manage, and monetize APIs. |
| 87 | + Key features include access control, usage analytics, and policy enforcement. |
| 88 | + The 3scale plugin synchronizes your 3scale content into the software catalog. |
| 89 | +spec: # Custom information processed by the Extensions plugin |
| 90 | + author: Red Hat # The Author of the plugin |
| 91 | + support: tech-preview # The Red Hat release status of the plugin |
| 92 | + lifecycle: active # The backstage lifecycle stage of the plugin |
| 93 | + publisher: Red Hat # Used to collect together plugins by the same author and display an extra line on the tile e/g/ "By Red Hat" |
| 94 | +
|
| 95 | + # The long description below is used in the Extension plugin's "Expanded Info" view as the plugin's long description. You should include information here about the the purpose of the plugin and how it integrates with RHDH. The description here uses Markdown fomat, but DON'T include images - they won't load if you do. |
| 96 | + description: | |
| 97 | + The 3scale Backstage plugin... |
| 98 | + (add further text here to really describe to the user what your plugin is for and how it integrates with RHDH's frontend/backend). |
| 99 | +
|
| 100 | + * Use bullets if you need to |
| 101 | +
|
| 102 | + ## Adding The Plugin To Red Hat Developer Hub |
| 103 | +
|
| 104 | + See the Red Hat Developer Hub documentation in the links below for details of how to install, activate, and configure plugins. |
| 105 | +
|
| 106 | + categories: # Categories show up in the tile view (limited to one) |
| 107 | + - API Management |
| 108 | + highlights: # Highlights show up on the extended information page |
| 109 | + - OpenShift support |
| 110 | + - Access Control & Security (Managed within 3scale) |
| 111 | + - Rate Limiting & Quotas (Managed within 3scale) |
| 112 | + - API Monetization Tools (Managed within 3scale) |
| 113 | + - Policy Enforcement (Managed within 3scale) |
| 114 | +
|
| 115 | + # Icons need to be base64 encoded SVG files, and can be inserted here (most are done already). |
| 116 | + icon: data:image/svg+xml;base64, |
| 117 | + PHN2ZyB3aWR0aD0iOTYiIGhlaWdodD0iOTYiIHZpZXdCb3g9IjAgMCA5NiA5NiIgZmlsbD0ibm9u |
| 118 | + etc... |
| 119 | +
|
| 120 | + # By linking to packages you enable the "Versions" section in the expanded information view |
| 121 | + packages: # Links to the pacjage name you set in the packages for this plugin |
| 122 | + - backstage-community-plugin-3scale-backend |
| 123 | +
|
| 124 | + # unused at the moment, but could allow for an image carousel later |
| 125 | + assets: |
| 126 | + - type: icon |
| 127 | + filename: img/3scale.svg |
| 128 | + originUri: https://github.com/backstage/backstage/blob/master/microsite/static/img/3scale.svg |
| 129 | + - type: image |
| 130 | + filename: img/backstage_dynatrace_plugin.png |
| 131 | + originUri: https://github.com/Dynatrace/backstage-plugin/blob/a307710edfb23a196c30790b9afceb9fb9af27df/docs/images/backstage_dynatrace_plugin.png |
| 132 | +
|
| 133 | + # Unused at the moment |
| 134 | + history: |
| 135 | + added: '2023-05-15' |
| 136 | +``` |
| 137 | + |
| 138 | +## `plugins/all.yaml` |
| 139 | + |
| 140 | +You **must** add your plugin yaml file to the list in the `plugins/all.yaml` file to get it picked up by RHDH and loaded into the catalog. To check if it's loading, check the catalog. |
| 141 | + |
| 142 | + |
| 143 | +# Using RHDH-local |
| 144 | + |
| 145 | +You need to reconfigure a few bits for the rhdh-1.5 image build, but when you do your local edits will show up within 15 secs... |
| 146 | + |
| 147 | +In `app-config.yaml` do this: |
| 148 | + |
| 149 | +```yaml:app-config.yaml |
| 150 | +
|
| 151 | +catalog: |
| 152 | + # Speed up the metadata refresh interval (when testing) |
| 153 | + processingInterval: { seconds: 15 } |
| 154 | +
|
| 155 | + locations: |
| 156 | + # Extensions Plugin needs this target to pull in the information about Plugins |
| 157 | + - type: file |
| 158 | + target: /marketplace/catalog-entities/plugins/all.yaml |
| 159 | + rules: |
| 160 | + - allow: [Location, Plugin] |
| 161 | + - type: file |
| 162 | + target: /marketplace/catalog-entities/packages/all.yaml |
| 163 | + rules: |
| 164 | + - allow: [Location, Package] |
| 165 | +
|
| 166 | +``` |
| 167 | + |
| 168 | +In `docker-compose.yaml` do this: |
| 169 | + |
| 170 | +```yaml:docker-compose.yaml |
| 171 | +services: |
| 172 | + rhdh: |
| 173 | + volumes: |
| 174 | + # Add an Extensions overwrite |
| 175 | + - type: bind |
| 176 | + source: <your rhdh cloned repo>/catalog-entities/marketplace/plugins/ |
| 177 | + target: /marketplace/catalog-entities/plugins |
| 178 | + - type: bind |
| 179 | + source: <your rhdh cloned repo>/catalog-entities/marketplace/packages/ |
| 180 | + target: /marketplace/catalog-entities/packages |
| 181 | +``` |
| 182 | + |
| 183 | +## Troubleshooting |
| 184 | + |
| 185 | +Some issues you may encounter and how to get around them. |
| 186 | + |
| 187 | +### Duplicate Entries |
| 188 | + |
| 189 | +Because Backstage doesn't remove catalog entries when the source changes, sometimes you will end up with duplicates. For example |
| 190 | +if you rename a plugin file, you may end up with the old catalog entry sticking around. To fix this you need to purge the |
| 191 | +backstage database. If running the in-memory database, this is easily acheived by restarting the container: |
| 192 | + |
| 193 | +```bash |
| 194 | +docker compose restart rhdh # or podman-compose restart rhdh |
5 | 195 | ``` |
| 196 | + |
| 197 | +### Catalog stops loading or refreshing |
| 198 | + |
| 199 | +Sometimes you might make a mistake with a plugin yaml file. If that happens you can use commenting of lines in the `plugins/all.yaml` |
| 200 | +to stop certain plugins from being loaded into the catalog. You can allso search for `all.yaml` in the RHDH logs to see if you can |
| 201 | +find a clue as to what caused the catalog entries to stop loading. For example: |
| 202 | + |
| 203 | +```bash |
| 204 | +rhdh | {"entity":"location:rhdh/plugins","level":"\u001b[33mwarn\u001b[39m","location":"file:/marketplace/catalog-entities/plugins/all.yaml","message":"YAML error at file:/marketplace/catalog-entities/plugins/keycloak-catalog-integration.yaml, YAMLParseError: Map keys must be unique at line 99, column 3:\n\n # level: tech-preview\n lifecycle: production\n ^\n","plugin":"catalog","service":"backstage","timestamp":"2025-03-11 15:56:57"} |
| 205 | +``` |
| 206 | + |
| 207 | +### Is my plugin here or missing? |
| 208 | + |
| 209 | +You can trace packages back to plugin entries using the VS Code "Find In Folder..." feature. For example: |
| 210 | + |
| 211 | +1. Given the plugin ID `@backstage-community/plugin-quay` (replace with the plugin ID you need) |
| 212 | +1. Do a "Find in Folder..." search for the `package/` file that contains this entry. |
| 213 | +1. The `/packages/backstage-community-plugin-quay.yaml` contains this entry. |
| 214 | +1. Open this file and look for the `metadata.name` (`backstage-community-plugin-quay`). |
| 215 | +1. Now do a search in the plugins folder for the text `backstage-community-plugin-quay`. |
| 216 | +1. The `plugins/backstage-community-plugin-quay.yaml` contains this text. |
| 217 | +1. You can open the file and edit the text. |
| 218 | + |
| 219 | +If you do not find a plugin.yaml associated with this plugin ID then it is probably missing and you need to create one. The |
| 220 | +file `1boilerplate.yaml` has a good starting point for creating these files. |
| 221 | + |
| 222 | + |
| 223 | +## Important Notes: |
| 224 | + |
| 225 | +* Plugins are manually created |
| 226 | +* Packages are generated with the command below |
| 227 | + |
| 228 | +```bash |
6 | 229 | # in rhdh root |
7 | 230 | npx --yes @red-hat-developer-hub/marketplace-cli generate --namespace rhdh -p dynamic-plugins.default.yaml -o catalog-entities/marketplace/packages |
8 | 231 | ``` |
0 commit comments