awslabs / aws-proton-plugins-for-backstage

AWS Proton plugins for Backstage

This repository contains a set of Backstage plugins for interacting with AWS Proton.

The plugins provide:

• An entity card to display the status of an AWS Proton service.
• A scaffolder action to create an AWS Proton service.

Demo

Installation

See AWS Proton plugins for Backstage installation guide.

Usage

For information about using the Proton plugins, see the following documents:

• AWS Proton plugins for Backstage reference
• Tutorial: using the AWS Proton plugins for Backstage

Development

For information about developing the Proton plugins locally, see Developing the AWS Proton plugins for Backstage.

Security

For information about contributing and reporting security issues, see CONTRIBUTING.

License

This project is licensed under the Apache-2.0 License.

N.B.: Although this repository is released under the Apache-2.0 license, its test dependencies include the third party rollup-plugin-dts project. The rollup-plugin-dts project's licensing includes the LGPL-3.0 license.

aws-proton-plugins-for-backstage's Issues

Feature: Environment scaffolder action

The Proton plugin currently only supports scaffolding a Proton service resource. For organizations where developers need to self-service create new environments (for example, new VPCs, container clusters, etc), the Proton plugin can add a scaffolding action for creating a Proton environment resource.

Feature: Display outputs in the Backstage entity card

We had a request to display Proton outputs in the Backstage entity card. For example, displaying the outputs of a pipeline resource, outputs of a service instance resource, and/or outputs of an environment resource. This request probably needs some further thought about where we draw the line of displaying everything in the Backstage UI vs providing surface-level information and a link to view more detailed information in the Proton console.

Add IAM permissions example to usage instructions

Note to self to add the least-privilege IAM permissions policy needed by the backend plugin to docs/usage.md. Users can use the sample policy when creating the AWS credentials/role that will be used by the backend plugin in their Backstage app.

For Tutorial, are we missing passing in AWS-managed provisioning role?

@niallthomson or @clareliguori ... thanks for your work on this plugin.

I followed the tutorial, including setting up a analect-gitops-aws-proton-user with the appropriate aws-proton policies, as mentioned in this issue. For now, I have added the same policies to my gitops user, in order to be able to work through the tutorial fully.

As part of the aws-proton setup wizard, you are asked to set up a provisioning pipeline role (see below).

It seems this is required to setup a proton environment (using the UI approach, at least).

Since I think the tutorial template is seeking to do this programmatically, then we are somehow not passing that arn-role for the pipeline-role into the docs/tutorial-assets/fargate-nginx-template/template.yaml file somewhere?

Perhaps this is related to why I am getting an error with missing permissioning for createServiceLinkedRole.

To address that temporarily, I added a new policy, although I'm not sure if that is superfluous if there is some fix to what I mention above.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "iam:CreateServiceLinkedRole",
            "Resource": "arn:aws:iam::*:role/aws-service-role/*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "ec2:DescribeAccountAttributes"
            ],
            "Resource": "*"
        }
    ]
}

On re-running the task, I then get blocked by the absence of the fargate-env ... whose creation I presume should be automated by this task ... but somehow it doesn't know about the pipeline-role. If you can offer any guidance for me to get this resolved. Thanks.

By the way, this was the ProtonRolePolicy-analect-io-aws-proton-pipeline-role, as generated by the Wizard.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "cloudformation:CancelUpdateStack",
                "cloudformation:ContinueUpdateRollback",
                "cloudformation:CreateChangeSet",
                "cloudformation:CreateStack",
                "cloudformation:DeleteChangeSet",
                "cloudformation:DeleteStack",
                "cloudformation:DescribeChangeSet",
                "cloudformation:DescribeStackDriftDetectionStatus",
                "cloudformation:DescribeStackEvents",
                "cloudformation:DescribeStackResourceDrifts",
                "cloudformation:DescribeStacks",
                "cloudformation:DetectStackResourceDrift",
                "cloudformation:ExecuteChangeSet",
                "cloudformation:ListChangeSets",
                "cloudformation:ListStackResources",
                "cloudformation:UpdateStack"
            ],
            "Resource": "arn:aws:cloudformation:*:xxxxxx:stack/AWSProton-*"
        },
        {
            "Effect": "Allow",
            "NotAction": [
                "organizations:*",
                "account:*"
            ],
            "Resource": "*",
            "Condition": {
                "ForAnyValue:StringEquals": {
                    "aws:CalledVia": [
                        "cloudformation.amazonaws.com"
                    ]
                }
            }
        },
        {
            "Effect": "Allow",
            "Action": [
                "organizations:DescribeOrganization",
                "account:ListRegions"
            ],
            "Resource": "*",
            "Condition": {
                "ForAnyValue:StringEquals": {
                    "aws:CalledVia": [
                        "cloudformation.amazonaws.com"
                    ]
                }
            }
        }
    ]
}

Ability to manage my Component within the Entity View

Feature Suggestion: Once my service and infrastructure is up and running and registered in the catalog there is always a need to make updates to the service or infrastructure day 2. Use cases include updating a service template to the latest version, introducing a new environment/variable or scaling up or down infrastructure resource limits. It would be ideal to offer the ability to make these changes from the entity page where a entity owner would have something like a Manage button where a pop up screen would appear allowing them to make configuration changes via the UI and those changes get committed back to source code once saved. I have seen this done with Kpt where a utility is used called ConfigSync which is similar to how git-sync works

Enhancement: isAWSProtonServiceAvailable signature should return Boolean

Currently the isAWSProtonServiceAvailable utility function ends up returning a string value, which means its necessary to do this in the most common use-case:

<EntitySwitch.Case if={e => Boolean(isAWSProtonServiceAvailable(e))}>

The function should return a Boolean to make its usage more convenient and follow the pattern of other similar Backstage utility functions like isGithubActionsAvailable (see GitHub Actions plugin):

<EntitySwitch.Case if={isAWSProtonServiceAvailable}>

Passing different credentials for backend-plugin and scaffolder

I followed in the installation instructions.
I created 2 new IAM users .. one for the backend-plugin with associated policy aws-proton-backend-user and one for the scaffolder aws-proton-scaffolder-user.

Back in app-config.yaml, how should one pass these credentials

aws:
  accounts:
    - accountId: 'aws-proton-backend-user'
      accessKeyId: ${MY_OTHER_ACCESS_KEY_ID}
      secretAccessKey: ${MY_OTHER_SECRET_ACCESS_KEY}
    - accountId: 'aws-proton-scaffolder-user'
      accessKeyId: ${YET_ANOTHER_ACCESS_KEY_ID}
      secretAccessKey: ${YET_ANOTHER_SECRET_ACCESS_KEY}

I'm not sure accountId can reference a user name such as aws-proton-backend-user .

Is it better to associate both policies here with a single user?

Thanks.

Feature: Environment entity card

Some users would like to view information about a Proton environment in the Backstage UI. Components in the Backstage catalog could be annotated with a Proton environment ARN, perhaps alongside other information for the environment like monitoring annotations. For example:

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: "prod-environment-123"
  description: "Production environment 123"
  annotations:
    aws.amazon.com/aws-proton-environment: arn:aws:proton:us-east-1:131296546870:environment/prod-123
    grafana/tag-selector: "prod-environment-123"
spec:
  type: environment
  lifecycle: production
  owner: "team-a"

The Proton plugin would provide a Proton environment entity card for the Backstage UI. The entity card could display similar information as the Proton service entity card like the deployment status of the environment, template version, etc.

Feature: Select Proton service template when creating component

Backstage supports the concept of Field Extensions which provide custom fields to capture information from the Backstage user when creating a Component.

Currently the only ways to populate the Proton service name is specifying it in the Backstage template or capture with free-form text input. This feature would add a custom Field Extension that lists the Proton service templates available by querying the API so that the user can dynamically select it.

Usage in a Backstage template:

apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: Test template
  title: Test template with custom extension
  description: Test template
spec:
  parameters:
    - title: Fill in some steps
      required:
        - protonServiceTemplate
      properties:
        protonServiceTemplate:
          title: Proton Service Template
          type: string
          description: The Proton Service Template to use
          ui:field: AwsProtonServiceTemplateExtension
[...]
  steps:
    - id: proton
      name: Create Proton Service
      action: aws:proton:create-service
      input:
        templateName: ${{ parameters.protonServiceTemplate }}
[...]

Enable various GitHub apps

This is a note to self to get the following GitHub apps enabled on this repo after we make the repo public:

• Semantic Pull Requests: https://github.com/apps/semantic-pull-requests
• Mergify: https://github.com/apps/mergify

Feature: Select Proton environment when creating a component

Similar to #82 (select a Proton service template), some Backstage templates using the Proton plugin will allow developers to choose which Proton environments their new service should be deployed to. It would be easier for the user to pick a Proton environment from a dropdown list than to type in the name of the environment.

For example, in this template snippet, the developer creating the Backstage component using the scaffolder will need to type in the names of the dev and prod Proton environments they want to use into a text box in the UI.

spec:
  parameters:
    - title: Select environments
      properties:
        dev_environment:
          title: Development Environment
          type: string
        prod_environment:
          title: Development Environment
          type: string
...
  steps:
    - id: template
      action: fetch:template
      input:
        url: ./skeleton
        values:
          aws_proton_dev_environment_name: ${{ parameters.dev_environment }}
          aws_proton_prod_environment_name: ${{ parameters.prod_environment }}

Backstage supports the concept of Field Extensions which provide custom fields to capture information from the Backstage user when creating a Component. This feature would add a custom Field Extension that lists the Proton environments available by querying the API so that the user can dynamically select it.

For example, the Backstage template would refer to the field extension for any environment parameters.

      properties:
        dev_environment:
          title: Development Environment
          type: string
          ui:field: AwsProtonEnvironmentPicker
        prod_environment:
          title: Development Environment
          type: string
          ui:field: AwsProtonEnvironmentPicker

Add npm publishing to release workflow

This is a note to self to add logic to the release workflow to publish new versions of the plugins to the npm registry. We'll do this once we get closer to the initial release and decide on the plugin names.