Skip to content

Commit

Permalink
fix(scaffolder): update annotator action readme (janus-idp#1638)
Browse files Browse the repository at this point in the history
  • Loading branch information
@debsmita1
debsmita1 authored May 31, 2024
1 parent 5ccbaa0 commit 8e3af1b
Show file tree
Hide file tree
Showing 9 changed files with 196 additions and 147 deletions.
143 changes: 104 additions & 39 deletions plugins/scaffolder-annotator-action/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,25 @@

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

This module enables users to generate custom actions for annotating their entity object(s).
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.

## Getting started
## Installation

### Installing on the new backend system
### Available custom actions

| Action | Description |
| ------------------------- | :-----------------------------------------------------------------------------------------------------: |
| `catalog:timestamping` | Adds the `backstage.io/createdAt` annotation containing the current timestamp to your entity object |
| `catalog:scaffolded-from` | Adds `scaffoldedFrom` spec containing the template entityRef to your entity object |
| `catalog:annotate` | Allows you to annotate your entity object with specified label(s), annotation(s) and spec property(ies) |

To begin, install the module package into the backend workspace of your backstage instance:

```console
yarn workspace backend add @janus-idp/backstage-scaffolder-backend-module-annotator
```

### Registering the annotator action plugin with the new backend system

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:

Expand All @@ -22,23 +36,17 @@ backend.add(
backend.start();
```

### Installing on the legacy backend system
### Registering the annotator action plugin with the legacy backend system

1. Install the Annotator custom action plugin using the following command:

```console
yarn workspace backend add @janus-idp/backstage-scaffolder-backend-module-annotator
```

2. Integrate the custom actions in the `scaffolder-backend` `createRouter` function:
1. Register the custom actions in the `packages/backend/src/plugins/scaffolder.ts` file:

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

```console
yarn workspace backend add @backstage/integration
```

- Add the `createTimestampAction` and `createScaffoldedFromAction` actions with the other built-in actions:
- Add the `createTimestampAction`, `createScaffoldedFromAction` and `createAnnotatorAction` with the other built-in actions:

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

Expand All @@ -49,7 +57,7 @@ yarn workspace backend add @janus-idp/backstage-scaffolder-backend-module-annota
createBuiltinActions,
createRouter,
} from '@backstage/plugin-scaffolder-backend';
import { createTimestampAction, createScaffoldedFromAction } from '@janus-idp/backstage-scaffolder-backend-module-annotator';
import { createTimestampAction, createScaffoldedFromAction, createAnnotatorAction } from '@janus-idp/backstage-scaffolder-backend-module-annotator';
/* highlight-add-end */
...

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


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

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:
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.

```yaml title="template.yaml"
steps:
Expand All @@ -95,7 +103,7 @@ steps:
# highlight-add-end
```

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:
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.

```yaml "title=template.yaml"
steps:
Expand All @@ -111,40 +119,97 @@ steps:

```

## Usage
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.

To use the `createAnnotatorAction` to create a custom action
```yaml "title=template.yaml"
steps:
- id: template
name: Fetch Skeleton + Template
action: fetch:template
...
# highlight-add-start
- id: add-fields-to-catalog-info
name: Add a few fields into `catalog-info.yaml` using the generic action
action: catalog:annotate
input:
labels:
custom: ${{ parameters.label }}
other: "test-label"
annotations:
custom.io/annotation: ${{ parameters.label }}
custom.io/other: "value"
# highlight-add-end

```

## Creating custom actions for your templates using the annotator module

### Create the custom action

#### The `createAnnotatorAction` action accepts the following parameters:

| Parameter Name | Type | Required | Description |
| ---------------------------------- | :------: | :------: | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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. |
| `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)." |
| `loggerInfoMsg` | `string` | No | A message that will be logged upon the execution of the action. Default: "Annotating your object" |
| `annotateEntityObject.labels` | `object` | No | Key-value pairs to be added to the `metadata.labels` of the entity |
| `annotateEntityObject.annotations` | `object` | No | Key-value pairs to be added to the `metadata.annotations` of the entity |
| `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. |

1. Create your [custom action](https://backstage.io/docs/features/software-templates/writing-custom-actions#writing-your-custom-action)

2. Add the annotator module package `@janus-idp/backstage-scaffolder-backend-module-annotator` into your module's `package.json`

| Parameter Name | Type | Required | Description |
| ---------------------------------- | :------: | :------: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `actionId` | `string` | Yes | A unique id for the action |
| `actionDescription` | `string` | Yes | A description of what the action accomplishes |
| `loggerInfoMsg` | `string` | No | A message that will be logged upon the execution of the action |
| `annotateEntityObject.labels` | `object` | No | Key-value pairs to be added to the `metadata.labels` of the entity |
| `annotateEntityObject.annotations` | `object` | No | Key-value pairs to be added to the `metadata.annotations` of the entity |
| `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. |
3. In the action file, add the following snippet to it:

The annotator action accepts the following inputs
```ts createAddCompanyTitleAction.ts
// highlight-add-start
import { createAnnotatorAction } from '@janus-idp/backstage-scaffolder-backend-module-annotator';

export const createAddCompanyTitleAction = () => {
return createAnnotatorAction(
'catalog:company-title',
'Creates a new `catalog:company-title` Scaffolder action to annotate scaffolded entities with the company title.',
'Annotating catalog-info.yaml with the company title',
);
};
// highlight-add-end
```

4. Install the custom action into your backstage instance following steps similar to the [installation instructions above](#installation)

### Use your custom action in your desired template(s)

#### The annotator template action accepts the following inputs

#### Input

| Parameter Name | Type | Required | Description |
| ---------------- | :------: | :------: | ----------------------------------------------------------------------------- |
| `labels` | `object` | No | Key-value pairs to be added to the `metadata.labels` of the entity |
| `annotations` | `object` | No | Key-value pairs to be added to the `metadata.annotations` of the entity |
| `entityFilePath` | `string` | No | The file path from which the YAML representation of the entity should be read |
| `objectYaml` | `object` | No | The YAML representation of the object/entity |
| `writeToFile` | `string` | No | The file path where the YAML representation of the entity should be stored |
| Parameter Name | Type | Required | Description |
| ---------------- | :------: | :------: | ------------------------------------------------------------------------------------------------------------------ |
| `labels` | `object` | No | Key-value pairs to be added to the `metadata.labels` of the entity |
| `annotations` | `object` | No | Key-value pairs to be added to the `metadata.annotations` of the entity |
| `spec` | `object` | No | Key-value pairs to be added to the `spec` of the entity |
| `entityFilePath` | `string` | No | The file path from which the YAML representation of the entity should be read |
| `objectYaml` | `object` | No | The YAML representation of the object/entity |
| `writeToFile` | `string` | No | The file path where the YAML representation of the entity should be stored. Default value is './catalog-info.yaml' |

#### Output

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

Here are the custom actions currently available:
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.

| Action | Description |
| ------------------------- | :-------------------------------------------: |
| `catalog:timestamping` | Adds current timestamp to your entity object |
| `catalog:scaffolded-from` | Adds template entityRef to your entity object |
```yaml
// highlight-add-start
- id: company-title
name: Add company title to catalog-info.yaml
action: catalog:company-title
input:
labels: {
company: 'My Company'
}
// highlight-add-end
```
17 changes: 16 additions & 1 deletion plugins/scaffolder-annotator-action/examples/templates/01-scaffolder-template.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -57,11 +57,25 @@ spec:
description: ${{ parameters.description }}
destination: ${{ parameters.repoUrl | parseRepoUrl }}
owner: ${{ parameters.owner }}


# this step is an example of using the `catalog:timestamping` action
- id: timestamp
name: Add Timestamp to catalog-info.yaml
action: catalog:timestamping

# this step is an example of using the `catalog:annotate` action
- id: add-fields-to-catalog-info
name: Add a few fields into `catalog-info.yaml` using the generic action
action: catalog:annotate
input:
labels:
custom: ${{ parameters.label }}
other: "test-label"
annotations:
custom.io/annotation: ${{ parameters.label }}
custom.io/other: "value"

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

- id: register
name: Register
Expand Down
33 changes: 24 additions & 9 deletions plugins/scaffolder-annotator-action/src/actions/annotator/annotator.test.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,6 @@ import * as yaml from 'yaml';

import { PassThrough } from 'stream';

import { convertLabelsToObject } from '../../utils/convertLabelsToObject';
import { getCurrentTimestamp } from '../../utils/getCurrentTimestamp';
import { createAnnotatorAction } from './annotator';

Expand Down Expand Up @@ -79,8 +78,16 @@ describe('catalog annotator', () => {
logger,
logStream: new PassThrough(),
input: {
labels: 'label1=value1;label2=value2;label3=value3',
annotations: 'annotation1=value1;annotation2=value2;annotation3=value3',
labels: {
label1: 'value1',
label2: 'value2',
label3: 'value3',
},
annotations: {
annotation1: 'value1',
annotation2: 'value2',
annotation3: 'value3',
},
},
output: jest.fn(),
createTemporaryDirectory() {
Expand All @@ -98,11 +105,11 @@ describe('catalog annotator', () => {
...entity.metadata,
labels: {
...entity.metadata.labels,
...convertLabelsToObject(mockContext.input.labels),
...mockContext.input.labels,
},
annotations: {
...entity.metadata.annotations,
...convertLabelsToObject(mockContext.input.annotations),
...mockContext.input.annotations,
},
},
};
Expand Down Expand Up @@ -144,8 +151,16 @@ describe('catalog annotator', () => {
logger,
logStream: new PassThrough(),
input: {
labels: 'label1=value1;label2=value2;label3=value3',
annotations: 'annotation1=value1;annotation2=value2;annotation3=value3',
labels: {
label1: 'value1',
label2: 'value2',
label3: 'value3',
},
annotations: {
annotation1: 'value1',
annotation2: 'value2',
annotation3: 'value3',
},
objectYaml: obj,
},
output: jest.fn(),
Expand All @@ -163,11 +178,11 @@ describe('catalog annotator', () => {
...obj.metadata,
labels: {
...(obj.metadata.labels || {}),
...convertLabelsToObject(mockContext.input.labels),
...mockContext.input.labels,
},
annotations: {
...(obj.metadata.annotations || {}),
...convertLabelsToObject(mockContext.input.annotations),
...mockContext.input.annotations,
},
},
};
Expand Down
Loading

0 comments on commit 8e3af1b

Please sign in to comment.