Skip to content

Commit 8e3af1b

Browse files
debsmita1debsmita1
authored
fix(scaffolder): update annotator action readme (#1638)
1 parent 5ccbaa0 commit 8e3af1b

File tree

9 files changed

+196
-147
lines changed

9 files changed

+196
-147
lines changed

‎plugins/scaffolder-annotator-action/README.md

Lines changed: 104 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -2,11 +2,25 @@
22

33
The annotator module for [@backstage/plugin-scaffolder-backend](https://www.npmjs.com/package/@backstage/plugin-scaffolder-backend).
44

5-
This module enables users to generate custom actions for annotating their entity object(s).
5+
This module allows users to create custom actions for annotating their entity objects. Additionally, it enables users to utilize existing custom actions provided by the module for annotating entities with timestamps and scaffolder entity references.
66

7-
## Getting started
7+
## Installation
88

9-
### Installing on the new backend system
9+
### Available custom actions
10+
11+
| Action | Description |
12+
| ------------------------- | :-----------------------------------------------------------------------------------------------------: |
13+
| `catalog:timestamping` | Adds the `backstage.io/createdAt` annotation containing the current timestamp to your entity object |
14+
| `catalog:scaffolded-from` | Adds `scaffoldedFrom` spec containing the template entityRef to your entity object |
15+
| `catalog:annotate` | Allows you to annotate your entity object with specified label(s), annotation(s) and spec property(ies) |
16+
17+
To begin, install the module package into the backend workspace of your backstage instance:
18+
19+
```console
20+
yarn workspace backend add @janus-idp/backstage-scaffolder-backend-module-annotator
21+
```
22+
23+
### Registering the annotator action plugin with the new backend system
1024

1125
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:
1226

@@ -22,23 +36,17 @@ backend.add(
2236
backend.start();
2337
```
2438

25-
### Installing on the legacy backend system
39+
### Registering the annotator action plugin with the legacy backend system
2640

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:
41+
1. Register the custom actions in the `packages/backend/src/plugins/scaffolder.ts` file:
3442

3543
- Install the `@backstage/integration` package using the following command:
3644

3745
```console
3846
yarn workspace backend add @backstage/integration
3947
```
4048

41-
- Add the `createTimestampAction` and `createScaffoldedFromAction` actions with the other built-in actions:
49+
- Add the `createTimestampAction`, `createScaffoldedFromAction` and `createAnnotatorAction` with the other built-in actions:
4250

4351
```ts title="packages/backend/src/plugins/scaffolder.ts"
4452

@@ -49,7 +57,7 @@ yarn workspace backend add @janus-idp/backstage-scaffolder-backend-module-annota
4957
createBuiltinActions,
5058
createRouter,
5159
} from '@backstage/plugin-scaffolder-backend';
52-
import { createTimestampAction, createScaffoldedFromAction } from '@janus-idp/backstage-scaffolder-backend-module-annotator';
60+
import { createTimestampAction, createScaffoldedFromAction, createAnnotatorAction } from '@janus-idp/backstage-scaffolder-backend-module-annotator';
5361
/* highlight-add-end */
5462
...
5563

@@ -67,7 +75,7 @@ yarn workspace backend add @janus-idp/backstage-scaffolder-backend-module-annota
6775
config: env.config,
6876
reader: env.reader,
6977
});
70-
const actions = [...builtInActions, createTimestampAction(), createScaffoldedFromAction()];
78+
const actions = [...builtInActions, createTimestampAction(), createScaffoldedFromAction(), createAnnotatorAction()];
7179
/* highlight-add-end */
7280

7381

@@ -79,7 +87,7 @@ yarn workspace backend add @janus-idp/backstage-scaffolder-backend-module-annota
7987
});
8088
```
8189

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:
90+
2. To annotate the `catalog-info.yaml` skeleton with the current timestamp, add the `catalog:timestamping` custom action in your template's YAML file after the `Fetch Skeleton + Template` step. Refer to the [example templates](./examples/) for examples on how it's used in a template.
8391

8492
```yaml title="template.yaml"
8593
steps:
@@ -95,7 +103,7 @@ steps:
95103
# highlight-add-end
96104
```
97105

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:
106+
3. To annotate the `catalog-info.yaml` skeleton with the template's `entityRef`, add the `catalog:scaffolded-from` custom action in your YAML file after the `Fetch Skeleton + Template` step. Refer to the [example templates](./examples/) for examples on how it is used in a template.
99107

100108
```yaml "title=template.yaml"
101109
steps:
@@ -111,40 +119,97 @@ steps:
111119

112120
```
113121

114-
## Usage
122+
4. To use the `catalog:annotate` action to annotate your entity object. Refer to the [example templates](./examples/) for examples on how it is used in a template.
115123

116-
To use the `createAnnotatorAction` to create a custom action
124+
```yaml "title=template.yaml"
125+
steps:
126+
- id: template
127+
name: Fetch Skeleton + Template
128+
action: fetch:template
129+
...
130+
# highlight-add-start
131+
- id: add-fields-to-catalog-info
132+
name: Add a few fields into `catalog-info.yaml` using the generic action
133+
action: catalog:annotate
134+
input:
135+
labels:
136+
custom: ${{ parameters.label }}
137+
other: "test-label"
138+
annotations:
139+
custom.io/annotation: ${{ parameters.label }}
140+
custom.io/other: "value"
141+
# highlight-add-end
142+
143+
```
144+
145+
## Creating custom actions for your templates using the annotator module
146+
147+
### Create the custom action
148+
149+
#### The `createAnnotatorAction` action accepts the following parameters:
150+
151+
| Parameter Name | Type | Required | Description |
152+
| ---------------------------------- | :------: | :------: | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
153+
| `actionId` | `string` | Yes | A unique id for the action. Default: `catalog:annotate`, please provide one or else it may conflict with the generic `catalog:annotate` custom action that is provided by this module. |
154+
| `actionDescription` | `string` | No | A description of what the action accomplishes. Default: "Creates a new scaffolder action to annotate the entity object with specified label(s), annotation(s) and spec property(ies)." |
155+
| `loggerInfoMsg` | `string` | No | A message that will be logged upon the execution of the action. Default: "Annotating your object" |
156+
| `annotateEntityObject.labels` | `object` | No | Key-value pairs to be added to the `metadata.labels` of the entity |
157+
| `annotateEntityObject.annotations` | `object` | No | Key-value pairs to be added to the `metadata.annotations` of the entity |
158+
| `annotateEntityObject.spec` | `object` | No | Key-value pairs to be added to the `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. |
159+
160+
1. Create your [custom action](https://backstage.io/docs/features/software-templates/writing-custom-actions#writing-your-custom-action)
161+
162+
2. Add the annotator module package `@janus-idp/backstage-scaffolder-backend-module-annotator` into your module's `package.json`
117163

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. |
164+
3. In the action file, add the following snippet to it:
126165

127-
The annotator action accepts the following inputs
166+
```ts createAddCompanyTitleAction.ts
167+
// highlight-add-start
168+
import { createAnnotatorAction } from '@janus-idp/backstage-scaffolder-backend-module-annotator';
169+
170+
export const createAddCompanyTitleAction = () => {
171+
return createAnnotatorAction(
172+
'catalog:company-title',
173+
'Creates a new `catalog:company-title` Scaffolder action to annotate scaffolded entities with the company title.',
174+
'Annotating catalog-info.yaml with the company title',
175+
);
176+
};
177+
// highlight-add-end
178+
```
179+
180+
4. Install the custom action into your backstage instance following steps similar to the [installation instructions above](#installation)
181+
182+
### Use your custom action in your desired template(s)
183+
184+
#### The annotator template action accepts the following inputs
128185

129186
#### Input
130187

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 |
188+
| Parameter Name | Type | Required | Description |
189+
| ---------------- | :------: | :------: | ------------------------------------------------------------------------------------------------------------------ |
190+
| `labels` | `object` | No | Key-value pairs to be added to the `metadata.labels` of the entity |
191+
| `annotations` | `object` | No | Key-value pairs to be added to the `metadata.annotations` of the entity |
192+
| `spec` | `object` | No | Key-value pairs to be added to the `spec` of the entity |
193+
| `entityFilePath` | `string` | No | The file path from which the YAML representation of the entity should be read |
194+
| `objectYaml` | `object` | No | The YAML representation of the object/entity |
195+
| `writeToFile` | `string` | No | The file path where the YAML representation of the entity should be stored. Default value is './catalog-info.yaml' |
138196

139197
#### Output
140198

141199
| Name | Type | Description |
142200
| ----------------- | :------: | -------------------------------------------------------------------------------------------- |
143201
| `annotatedObject` | `object` | The entity object marked with your specified annotation(s), label(s), and spec property(ies) |
144202

145-
Here are the custom actions currently available:
203+
To annotate the entity file, add your custom action to your template file after `Fetch Skeleton + Template` step. Please note that your custom action needs to be installed into the backstage instance running the software template.
146204

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 |
205+
```yaml
206+
// highlight-add-start
207+
- id: company-title
208+
name: Add company title to catalog-info.yaml
209+
action: catalog:company-title
210+
input:
211+
labels: {
212+
company: 'My Company'
213+
}
214+
// highlight-add-end
215+
```

‎plugins/scaffolder-annotator-action/examples/templates/01-scaffolder-template.yaml

Lines changed: 16 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -57,11 +57,25 @@ spec:
5757
description: ${{ parameters.description }}
5858
destination: ${{ parameters.repoUrl | parseRepoUrl }}
5959
owner: ${{ parameters.owner }}
60-
60+
61+
# this step is an example of using the `catalog:timestamping` action
6162
- id: timestamp
6263
name: Add Timestamp to catalog-info.yaml
6364
action: catalog:timestamping
65+
66+
# this step is an example of using the `catalog:annotate` action
67+
- id: add-fields-to-catalog-info
68+
name: Add a few fields into `catalog-info.yaml` using the generic action
69+
action: catalog:annotate
70+
input:
71+
labels:
72+
custom: ${{ parameters.label }}
73+
other: "test-label"
74+
annotations:
75+
custom.io/annotation: ${{ parameters.label }}
76+
custom.io/other: "value"
6477

78+
# this step is an example of using the `catalog:scaffolded-from` action
6579
- id: append-templateRef
6680
name: Append the entityRef of this template to the entityRef
6781
action: catalog:scaffolded-from
@@ -74,6 +88,7 @@ spec:
7488
- github.com
7589
description: This is ${{ parameters.component_id }}
7690
repoUrl: ${{ parameters.repoUrl }}
91+
repoVisibility: public
7792

7893
- id: register
7994
name: Register

‎plugins/scaffolder-annotator-action/src/actions/annotator/annotator.test.ts

Lines changed: 24 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,6 @@ import * as yaml from 'yaml';
55

66
import { PassThrough } from 'stream';
77

8-
import { convertLabelsToObject } from '../../utils/convertLabelsToObject';
98
import { getCurrentTimestamp } from '../../utils/getCurrentTimestamp';
109
import { createAnnotatorAction } from './annotator';
1110

@@ -79,8 +78,16 @@ describe('catalog annotator', () => {
7978
logger,
8079
logStream: new PassThrough(),
8180
input: {
82-
labels: 'label1=value1;label2=value2;label3=value3',
83-
annotations: 'annotation1=value1;annotation2=value2;annotation3=value3',
81+
labels: {
82+
label1: 'value1',
83+
label2: 'value2',
84+
label3: 'value3',
85+
},
86+
annotations: {
87+
annotation1: 'value1',
88+
annotation2: 'value2',
89+
annotation3: 'value3',
90+
},
8491
},
8592
output: jest.fn(),
8693
createTemporaryDirectory() {
@@ -98,11 +105,11 @@ describe('catalog annotator', () => {
98105
...entity.metadata,
99106
labels: {
100107
...entity.metadata.labels,
101-
...convertLabelsToObject(mockContext.input.labels),
108+
...mockContext.input.labels,
102109
},
103110
annotations: {
104111
...entity.metadata.annotations,
105-
...convertLabelsToObject(mockContext.input.annotations),
112+
...mockContext.input.annotations,
106113
},
107114
},
108115
};
@@ -144,8 +151,16 @@ describe('catalog annotator', () => {
144151
logger,
145152
logStream: new PassThrough(),
146153
input: {
147-
labels: 'label1=value1;label2=value2;label3=value3',
148-
annotations: 'annotation1=value1;annotation2=value2;annotation3=value3',
154+
labels: {
155+
label1: 'value1',
156+
label2: 'value2',
157+
label3: 'value3',
158+
},
159+
annotations: {
160+
annotation1: 'value1',
161+
annotation2: 'value2',
162+
annotation3: 'value3',
163+
},
149164
objectYaml: obj,
150165
},
151166
output: jest.fn(),
@@ -163,11 +178,11 @@ describe('catalog annotator', () => {
163178
...obj.metadata,
164179
labels: {
165180
...(obj.metadata.labels || {}),
166-
...convertLabelsToObject(mockContext.input.labels),
181+
...mockContext.input.labels,
167182
},
168183
annotations: {
169184
...(obj.metadata.annotations || {}),
170-
...convertLabelsToObject(mockContext.input.annotations),
185+
...mockContext.input.annotations,
171186
},
172187
},
173188
};

0 commit comments

Comments
 (0)