AWS Streamlined CI/CD - ASCC

ASCC aims at simplifying the creation of a proper CI/CD pipeline for SST applications, using AWS CodePipeline.

Pipelines created with this utility are able to deploy to any number of specified regions, and have three stages: alpha, staging, prod.

Here's what the pipeline looks like:

Supported Languages

Currently, this pipeline only supports NodeJS SST applications. It should be possible to build a pipeline for any kind of SST applications with docker. Feel free to open pull requests to add other Dockerfiles for other languages.

Supported Repository Providers

The only supported repository provider for now is GitHub.

It should be relatively easy to add support for CodeCommit or BitBucket, since they are both supported by AWS CodePipeline.

TODO:

• test the whole thing
• Finish readme section

Using ASCC

1. Install ASCC

npm install -g ascc

or

npm install --save-dev ascc

2. Build Dockerfile

Copy one of the example Dockerfiles, paste it at the root of your directory, and tune it to your needs.

3. Parameters

Create a parameters file for your pipeline

ASCC expects a JSON file with a predetermined set of parameters. Take a peak at the example, or at the full schema the JSON schema for all the details.

4. Create A Secret For Your Repository Credentials

To be able to checkout your source code, ASCC needs a token that authorizes it to your repository. You will need to store that token in a Secrets Manager secret, with the name that you have defined in your parameters file.

GitHub personnal access token creation. The personnal token should have the following access:

• repo - to read the repository
• admin:repo_hook - if you plan to use webhooks

5. Create Your CICD Pipeline

ascc create --params-file path/to/your/params/file [--aws-profile your_profile]

This will create all the required resources for your CI/CD pipeline. AWS CodePipeline will run the pipeline once by default, but it will fail to deploy. You need to complete the next step for deployment to succeed.

If you need to update your pipeline because you've changed parameters, simply re-run the command above.

ASCC will use your default AWS profile, or any other profile that you can specify with the --aws-profile option.

6. Create Target Deployment Roles

ASCC does not know the permissions needed to deploy your application, and it also does not create roles with admin access to your account for security best practices reasons. Instead, for the deployment to each stage, ASCC will assume a role that you should create, which should contain all the permissions required to deploy your application. After running the create command, you will have the ARNs for each deployment role in your terminal. You will need to use them to create a role for each stage, in the AWS account associated with that stage, with the following parameters:

Name: --AsccTargetDeploymentRole, e.g. myApp-Alpha-AsccTargetDeploymentRole. ASCC will assume a role with this name. Trust policy:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "Statement1",
      "Effect": "Allow",
      "Principal": {
        "AWS": "<role_arn_from_terminal>"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

Policies: Whatever is needed to deploy your application

7. Remove Your CICD Pipeline

This will remove the resources for your CI/CD pipeline, but not the resources for your application. You will need to delete the CloudFormation stacks manually in your AWS accounts if you want to also remove your application resources.

ascc remove --params-file path/to/your/params/file [--aws-profile your_profile]

Road Map

• [ ] Add support for end-to-end tests based on user-defined AWS Lambda Functions