AWS scaffolder actions plugin for Backstage

This is the AWS scaffolder actions plugin for backstage.io.

It provides scaffolder actions to:

• Create AWS resources using the AWS Cloud Control API
• Post an event to AWS EventBridge via the PutEvents API
• Publish files to an Amazon S3 bucket
• Create and publish files to a new AWS CodeCommit repository

Installing

This guide assumes that you are familiar with the general Getting Started documentation and have assumes you have an existing Backstage application.

Install the backend package in your Backstage app:

yarn workspace backend add @aws/aws-core-plugin-for-backstage-scaffolder-actions

Add the scaffolder module to the packages/backend/src/index.ts:

const backend = createBackend();
// ...
backend.add(import('@aws/aws-core-plugin-for-backstage-scaffolder-actions'));
// ...
backend.start();

Actions

Each action is documented below.

AWS Cloud Control - Create resource

This scaffolder action creates AWS resources using the AWS Cloud Control API.

Note: Creating AWS resources using this mechanism is generally discouraged unless for exceptional use-cases. We strongly recommend relying on infrastructure-as-code to create AWS resources, and using this action for anything that is strictly related to bootstrapping a project.

Permissions

The IAM role(s) used by Backstage will require the following permissions:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["cloudcontrol:CreateResource"],
      "Resource": "*"
    }
  ]
}

Note: This policy does not reflect least privilege and you should further limit the policy to the appropriate AWS resources.

Usage

The scaffolder action can be included in a software template like so:

steps:
  - id: create-ecr-repository
    name: Create ECR Repository
    action: aws:cloudcontrol:create
    input:
      typeName: 'AWS::ECR::Repository'
      desiredState: '{"RepositoryName": "${{ parameters.name }}-ecr-repository"}'
      wait: true
      maxWaitTime: 20

Amazon EventBridge - Post event

This scaffolder action posts an event to an Amazon EventBridge event bus using the PutEvents API.

Permissions

The IAM role(s) used by Backstage will require the following permissions:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["events:PutEvents"],
      "Resource": "*"
    }
  ]
}

Note: This policy does not reflect least privilege and you should further limit the policy to the appropriate AWS resources.

Usage

The scaffolder action can be included in a software template like so:

steps:
  - id: eventbridge-event
    name: Post EventBridge event
    action: aws:eventbridge:event
    input:
      region: us-east-1
      eventBusName: my-event-bus
      source: my-app
      detailType: MyDetailType
      detail: '{"key": "value"}'

You can alternatively pass the detail as an object using detailObject:

steps:
  - id: eventbridge-event
    name: Post EventBridge event
    action: aws:eventbridge:event
    input:
      eventBusName: my-event-bus
      source: my-app
      detailType: MyDetailType
      detailObject:
        key: value

Amazon S3 - Copy files

This scaffolder action copies files from the scaffolder workspace to an Amazon S3 bucket. By default, it uploads all files present in the workspace, so any content generated by prior steps (e.g. fetch:template) will be included. Use the path input to limit which files are copied.

Permissions

The IAM role(s) used by Backstage will require the following permissions:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["s3:PutObject"],
      "Resource": "*"
    }
  ]
}

Note: This policy does not reflect least privilege and you should further limit the policy to the appropriate AWS resources.

Usage

The scaffolder action can be included in a software template like so:

steps:
  - id: template
    name: Fetch Skeleton
    action: fetch:template
    input:
      url: ./skeleton
      targetPath: ./skeleton
  - id: copyFiles
    name: Copy files to S3
    action: aws:s3:cp
    input:
      bucketName: my-bucket
      region: us-east-1

You can also specify a file pattern and prefix:

steps:
  - id: copyFiles
    name: Copy files to s3
    action: aws:s3:cp
    input:
      accountId: '1234567890'
      region: us-east-1
      bucketName: my-bucket
      path: 'build/**'
      prefix: 'artifacts/'

AWS CodeCommit - Publish repository

This scaffolder action creates a new AWS CodeCommit repository and publishes the workspace contents to it.

Permissions

The IAM role(s) used by Backstage will require the following permissions:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["codecommit:CreateRepository", "codecommit:CreateCommit"],
      "Resource": "*"
    }
  ]
}

Note: This policy does not reflect least privilege and you should further limit the policy to the appropriate AWS resources.

Usage

The scaffolder action can be included in a software template like so:

steps:
  - id: publish
    name: Publish to CodeCommit
    action: aws:codecommit:publish
    input:
      repositoryName: my-new-repo
      defaultBranch: main

With custom author and a subdirectory:

steps:
  - id: publish
    name: Publish to CodeCommit
    action: aws:codecommit:publish
    input:
      accountId: '1234567890'
      region: us-west-2
      repositoryName: my-new-repo
      defaultBranch: main
      sourcePath: ./output
      gitCommitMessage: 'Initial scaffolded commit'
      gitAuthorName: Backstage
      gitAuthorEmail: [email protected]