|
| 1 | +# Annotator custom action for Scaffolder Backstage |
| 2 | + |
| 3 | +The annotator module for [@backstage/plugin-scaffolder-backend](https://www.npmjs.com/package/@backstage/plugin-scaffolder-backend). |
| 4 | + |
| 5 | +This module enables users to generate custom actions for annotating their entity object(s). |
| 6 | + |
| 7 | +## Getting started |
| 8 | + |
| 9 | +### Installing on the new backend system |
| 10 | + |
| 11 | +To install the module into the [new backend system](https://backstage.io/docs/backend-system/), add the following into the `packages/backend/src/index.ts` file: |
| 12 | + |
| 13 | +```ts title="packages/backend/src/index.ts |
| 14 | +const backend = createBackend(); |
| 15 | + |
| 16 | +// highlight-add-start |
| 17 | +backend.add( |
| 18 | + import('@janus-idp/backstage-scaffolder-backend-module-annotator/alpha'), |
| 19 | +); |
| 20 | +// highlight-add-end |
| 21 | + |
| 22 | +backend.start(); |
| 23 | +``` |
| 24 | + |
| 25 | +### Installing on the legacy backend system |
| 26 | + |
| 27 | +1. Install the Annotator custom action plugin using the following command: |
| 28 | + |
| 29 | +```console |
| 30 | +yarn workspace backend add @janus-idp/backstage-scaffolder-backend-module-annotator |
| 31 | +``` |
| 32 | + |
| 33 | +2. Integrate the custom actions in the `scaffolder-backend` `createRouter` function: |
| 34 | + |
| 35 | +- Install the `@backstage/integration` package using the following command: |
| 36 | + |
| 37 | + ```console |
| 38 | + yarn workspace backend add @backstage/integration |
| 39 | + ``` |
| 40 | + |
| 41 | +- Add the `createTimestampAction` and `createScaffoldedFromAction` actions with the other built-in actions: |
| 42 | + |
| 43 | + ```ts title="packages/backend/src/plugins/scaffolder.ts" |
| 44 | + |
| 45 | + import { CatalogClient } from '@backstage/catalog-client'; |
| 46 | + /* highlight-add-start */ |
| 47 | + import { ScmIntegrations } from '@backstage/integration'; |
| 48 | + import { |
| 49 | + createBuiltinActions, |
| 50 | + createRouter, |
| 51 | + } from '@backstage/plugin-scaffolder-backend'; |
| 52 | + import { createTimestampAction, createScaffoldedFromAction } from '@janus-idp/backstage-scaffolder-backend-module-annotator'; |
| 53 | + /* highlight-add-end */ |
| 54 | + ... |
| 55 | + |
| 56 | + export default async function createPlugin( |
| 57 | + const catalogClient = new CatalogClient({ |
| 58 | + discoveryApi: env.discovery, |
| 59 | + }); |
| 60 | + |
| 61 | + /* highlight-add-start */ |
| 62 | + const integrations = ScmIntegrations.fromConfig(env.config); |
| 63 | + |
| 64 | + const builtInActions = createBuiltinActions({ |
| 65 | + integrations: integrations as any, |
| 66 | + catalogClient, |
| 67 | + config: env.config, |
| 68 | + reader: env.reader, |
| 69 | + }); |
| 70 | + const actions = [...builtInActions, createTimestampAction(), createScaffoldedFromAction()]; |
| 71 | + /* highlight-add-end */ |
| 72 | + |
| 73 | + |
| 74 | + return await createRouter({ |
| 75 | + /* highlight-add-next-line */ |
| 76 | + actions, |
| 77 | + logger: env.logger, |
| 78 | + ... |
| 79 | + }); |
| 80 | + ``` |
| 81 | + |
| 82 | +3. To annotate the catalog-info.yaml skeleton with the current timestamp, add the **catalog:timestamping** custom action in your template yaml after the `Fetch Skeleton + Template` step: |
| 83 | + |
| 84 | +```yaml title="template.yaml" |
| 85 | +steps: |
| 86 | + - id: template |
| 87 | + name: Fetch Skeleton + Template |
| 88 | + action: fetch:template |
| 89 | + ... |
| 90 | + |
| 91 | + # highlight-add-start |
| 92 | + - id: timestamp |
| 93 | + name: Add Timestamp to catalog-info.yaml |
| 94 | + action: catalog:timestamping |
| 95 | + # highlight-add-end |
| 96 | +``` |
| 97 | + |
| 98 | +4. To annotate the catalog-info.yaml skeleton with the template entityRef, add the **catalog:scaffolded-from** custom action in your template yaml after the `Fetch Skeleton + Template` step: |
| 99 | + |
| 100 | +```yaml "title=template.yaml" |
| 101 | +steps: |
| 102 | + - id: template |
| 103 | + name: Fetch Skeleton + Template |
| 104 | + action: fetch:template |
| 105 | + ... |
| 106 | + # highlight-add-start |
| 107 | + - id: append-templateRef |
| 108 | + name: Append the entityRef of this template to the entityRef |
| 109 | + action: catalog:scaffolded-from |
| 110 | + # highlight-add-end |
| 111 | + |
| 112 | +``` |
| 113 | + |
| 114 | +## Usage |
| 115 | + |
| 116 | +To use the `createAnnotatorAction` to create a custom action |
| 117 | + |
| 118 | +| Parameter Name | Type | Required | Description | |
| 119 | +| ---------------------------------- | :------: | :------: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | |
| 120 | +| `actionId` | `string` | Yes | A unique id for the action | |
| 121 | +| `actionDescription` | `string` | Yes | A description of what the action accomplishes | |
| 122 | +| `loggerInfoMsg` | `string` | No | A message that will be logged upon the execution of the action | |
| 123 | +| `annotateEntityObject.labels` | `object` | No | Key-value pairs to be added to the `metadata.labels` of the entity | |
| 124 | +| `annotateEntityObject.annotations` | `object` | No | Key-value pairs to be added to the `metadata.annotations` of the entity | |
| 125 | +| `annotateEntityObject.spec` | `object` | No | Key-value pairs to be added to the `metadata.spec` of the entity. The value for each key can either be a string or an object with the key `readFromContext`, enabling users to specify the path in the context from which the value should be retrieved. | |
| 126 | + |
| 127 | +The annotator action accepts the following inputs |
| 128 | + |
| 129 | +#### Input |
| 130 | + |
| 131 | +| Parameter Name | Type | Required | Description | |
| 132 | +| ---------------- | :------: | :------: | ----------------------------------------------------------------------------- | |
| 133 | +| `labels` | `object` | No | Key-value pairs to be added to the `metadata.labels` of the entity | |
| 134 | +| `annotations` | `object` | No | Key-value pairs to be added to the `metadata.annotations` of the entity | |
| 135 | +| `entityFilePath` | `string` | No | The file path from which the YAML representation of the entity should be read | |
| 136 | +| `objectYaml` | `object` | No | The YAML representation of the object/entity | |
| 137 | +| `writeToFile` | `string` | No | The file path where the YAML representation of the entity should be stored | |
| 138 | + |
| 139 | +#### Output |
| 140 | + |
| 141 | +| Name | Type | Description | |
| 142 | +| ----------------- | :------: | -------------------------------------------------------------------------------------------- | |
| 143 | +| `annotatedObject` | `object` | The entity object marked with your specified annotation(s), label(s), and spec property(ies) | |
| 144 | + |
| 145 | +Here are the custom actions currently available: |
| 146 | + |
| 147 | +| Action | Description | |
| 148 | +| ------------------------- | :-------------------------------------------: | |
| 149 | +| `catalog:timestamping` | Adds current timestamp to your entity object | |
| 150 | +| `catalog:scaffolded-from` | Adds template entityRef to your entity object | |
0 commit comments