Expected Project Structure

Need to discuss this section

The Pipeline Builder has some minimal requirements regarding the projects that deploys. It requires the existence of certain files, and it requires the existence of specific content in some of these files.

Required files

Pipline Builder requires 3 files:

1. A CloudFormation template with name template.yml
   • This file defines the resources that the project is going to use.
2. A CodeBuild buildspec file with name buildspec.yml
   • This file defines the commands that are going to be run during the CodeBuild phase
3. A CodeBuild buildspec file with name testspec.yml
   • This file defines the commands that need to be executed for running end-to-end tests.
4. A policy document json file with name createStackRolePolicyDocument.json
   • This document defines the policies that will allow CodePipeline to create and deploy the resources of the deployed service (See comment at the end of the page).

Unclear what these are and where the values come from

Requirements for the template.yml file.

Example file

You can always refer to this example file that satisfies all requirements.

Requirement 1.A : Template Parameters

The template file needs to define the parameters shown below. These parameters all filled in automatically by the Pipeline Builder. You do not need to set any default values or pass any values for these parameters. More details about the parameters can be found here

Parameters:
  ProjectId:
   Type: String
   Description: Automatically generated ProjectId based on repository and branch
 Stage:
  Type: String
  Description: Deployment stage. Either TEST or FINAL
 Branch:
  Type: String
  Description: The Git branch
 CodeBucket:
  Type: String
  Description: Automatically generated S3 bucket where the code is stored
 InitFunctionName:
  Type: String
  Description: Automatically generated name for the initialization function
 DestroyFunctionName:
  Type:  String
  Description: Automatically generated name for the destroy function 

Requirement 1.B: Init and Destroy functions

Describe the usefulness of these methods

The template file needs to define two lambda functions. One for resource initialization (InitFunction) after the stack has been created, and one for undoing the initialization (DestroyFunction) before the stack is deleted. These functions do not need to do anything, if all the resources can be configured during the stack creation by the provided CloudFormation file.

The purpose of the InitFunction is to perform deploy operations that cannot be done through a CloudFormation template file. For example, InitFunction could link an AWS resource with an external resource, such as publishing an APIGateway documentation to SwaggerHub.

Function names: The FunctionName property for the functions should be !Ref InitFunctionName and !Ref DestroyFunctionName respectively.

Example functions: The project pipeline-builder-sample-projects provides two examples of functions. One in Java and one embedded in the CloudFormation template in Javascript. Both functions have no functionality. The just return a success message to CodePipeline.

Requirement 1.C : Add a Transform section

Why?*

Add the Serverless transform macros in your project by adding this line before setting the parameters of the project. Transform: AWS::Serverless-2016-10-31 This is required for transforming AWS::Serverless resources to normal AWS resources.

Requirements for the buildspec.yml file.

Build phase:

In the build phase of the file, the last command of the build phase should be the following:

cloudformation package --template template.yml --s3-bucket $S3_BUCKET --output-template template-export.yml

This command copies the code and all the resources to the $S3_BUCKET and transforms the local paths of the file template.yml to S3 paths.

Requirements for the testspec.yml file

Except for it being a valid buildspec file, there are no other requirements for this file.

Comments

Comment 1.

The file createStackRolePolicyDocument.json defines the policies for creating the services of the service being deployed. If for example, our service requires an EC2 instance, then our createStackRolePolicyDocument.json file might contain an "ec2:startInstances" policy.

Any policies that are necessary for our service to run should be defined in the CloudFormation template template.yml. For example, if our EC2 instance is a server accessing a Dynamo database then probably we would need to add an access policy in the template.yml such as dynamodb:UpdateItem.