Prerequisites Step 1: Create a source repository Step 2: Create AWS roles Step 3: Add AWS roles to CodeCatalyst Step 4: Create an Amazon S3 bucket Step 5: Add source files Step 6: Create and run a workflow Step 7: Make a change Clean up

Tutorial: Deploy a serverless application

In this tutorial, you learn how to build, test, and deploy a serverless application as a CloudFormation stack using a workflow.

The application in this tutorial is a simple web application that outputs a 'Hello World' message. It consists of an AWS Lambda function and an Amazon API Gateway, and you build it using the AWS Serverless Application Model (AWS SAM), which is an extension of CloudFormation.

Prerequisites

Before you begin:

You need a CodeCatalyst space with a connected AWS account. For more information, see Creating a space.
In your space, you need an empty project called:
```
codecatalyst-cfn-project
```
Use the Start from scratch option to create this project.

For more information, see Creating an empty project in Amazon CodeCatalyst.
In your project, you need a CodeCatalyst environment called:
```
codecatalyst-cfn-environment
```
Configure this environment as follows:
- Choose any type, such as Non-production.
- Connect your AWS account to it.
- For the Default IAM role, choose any role. You'll specify a different role later.
For more information, see Deploying into AWS accounts and VPCs.

Step 1: Create a source repository

In this step, you create a source repository in CodeCatalyst. This repository is used to store the tutorial's source files, such as the Lambda function file.

For more information about source repositories, see Creating a source repository.

To create a source repository

In CodeCatalyst, in the navigation pane, choose Code, and then choose Source repositories.
Choose Add repository, and then choose Create repository.
In Repository name, enter:
```
codecatalyst-cfn-source-repository
```
Choose Create.

You have now created a repository called codecatalyst-cfn-source-repository.

Step 2: Create AWS roles

In this step, you create the following AWS IAM roles:

Deploy role – Grants the CodeCatalyst Deploy CloudFormation stack action permission to access your AWS account and CloudFormation service where you’ll deploy your serverless application. The Deploy CloudFormation stack action is part of your workflow.
Build role – Grants the CodeCatalyst build action permission to access your AWS account and write to Amazon S3 where your serverless application package will be stored. The build action is part of your workflow.
Stack role – Grants CloudFormation permission to read and modify the resources specified in the AWS SAM template that you will provide later. Also grants permission to CloudWatch.

For more information about IAM roles, see IAM roles in the AWS Identity and Access Management User Guide.

Note

To save time, you can create a single role, called the CodeCatalystWorkflowDevelopmentRole-spaceName role, instead of the three roles listed previously. For more information, see Creating the CodeCatalystWorkflowDevelopmentRole-spaceName role for your account and space. Understand that the CodeCatalystWorkflowDevelopmentRole-spaceName role has very broad permissions that may pose a security risk. We recommend that you only use this role in tutorials and scenarios where security is less of a concern. This tutorial assumes you are creating the three roles listed previously.

Note

A Lambda execution role is also required, but you don't need to create it now because the sam-template.yml file creates it for you when you run the workflow in step 5.

To create a deploy role

Create a policy for the role, as follows:
1. Sign in to AWS.
2. Open the IAM console at https://console.aws.amazon.com/iam/.
3. In the navigation pane, choose Policies.
4. Choose Create policy.
5. Choose the JSON tab.
6. Delete the existing code.
7. Paste the following code:
  Note
  The first time the role is used to run workflow actions, use the wildcard in the resource policy statement and then scope down the policy with the resource name after it is available.
```
"Resource": "*"
```
8. Choose Next: Tags.
9. Choose Next: Review.
10. In Name, enter:
```
codecatalyst-deploy-policy
```
11. Choose Create policy.
  
  You have now created a permissions policy.
Create the deploy role, as follows:
1. In the navigation pane, choose Roles, and then choose Create role.
2. Choose Custom trust policy.
3. Delete the existing custom trust policy.
4. Add the following custom trust policy:
5. Choose Next.
6. In Permissions policies, search for codecatalyst-deploy-policy and select its check box.
7. Choose Next.
8. For Role name, enter:
```
codecatalyst-deploy-role
```
9. For Role description, enter:
```
CodeCatalyst deploy role
```
10. Choose Create role.
You have now created a deploy role with a trust policy and permissions policy.
Obtain the deploy role ARN, as follows:
1. In the navigation pane, choose Roles.
2. In the search box, enter the name of the role you just created (codecatalyst-deploy-role).
3. Choose the role from the list.
  
  The role's Summary page appears.
4. At the top, copy the ARN value.
You have now created the deploy role with the appropriate permissions, and obtained its ARN.

To create a build role

Create a policy for the role, as follows:
1. Sign in to AWS.
2. Open the IAM console at https://console.aws.amazon.com/iam/.
3. In the navigation pane, choose Policies.
4. Choose Create policy.
5. Choose the JSON tab.
6. Delete the existing code.
7. Paste the following code:
  Note
  The first time the role is used to run workflow actions, use the wildcard in the resource policy statement and then scope down the policy with the resource name after it is available.
```
"Resource": "*"
```
8. Choose Next: Tags.
9. Choose Next: Review.
10. In Name, enter:
```
codecatalyst-build-policy
```
11. Choose Create policy.
  
  You have now created a permissions policy.
Create the build role, as follows:
1. In the navigation pane, choose Roles, and then choose Create role.
2. Choose Custom trust policy.
3. Delete the existing custom trust policy.
4. Add the following custom trust policy:
5. Choose Next.
6. In Permissions policies, search for codecatalyst-build-policy and select its check box.
7. Choose Next.
8. For Role name, enter:
```
codecatalyst-build-role
```
9. For Role description, enter:
```
CodeCatalyst build role
```
10. Choose Create role.
You have now created a build role with a trust policy and permissions policy.
Obtain the build role ARN, as follows:
1. In the navigation pane, choose Roles.
2. In the search box, enter the name of the role you just created (codecatalyst-build-role).
3. Choose the role from the list.
  
  The role's Summary page appears.
4. At the top, copy the ARN value.
You have now created the build role with the appropriate permissions, and obtained its ARN.

To create a stack role

Sign in to AWS using the account where you want to deploy your stack.
Open the IAM console at https://console.aws.amazon.com/iam/.
Create the stack role as follows:
1. In the navigation pane, choose Roles.
2. Choose Create role.
3. Choose AWS service.
4. In the Use case section, choose CloudFormation from the drop-down list.
5. Select the CloudFormation radio button.
6. At the bottom, choose Next.
7. Using the search box, find the following permissions policies, and then select their respective check boxes.
  
  Note
  If you search for a policy and it doesn't appear, make sure to choose Clear filters and try again.
  - CloudWatchFullAccess
  - AWSCloudFormationFullAccess
  - IAMFullAccess
  - AWSLambda_FullAccess
  - AmazonAPIGatewayAdministrator
  - AmazonS3FullAccess
  - AmazonEC2ContainerRegistryFullAccess
  The first policy allows access to CloudWatch to enable stack rollbacks when an alarm occurs.
  
  The remaining policies allow AWS SAM to access the services and resources in the stack that will be deployed in this tutorial. For more information, see Permissions in the AWS Serverless Application Model Developer Guide.
8. Choose Next.
9. For Role name, enter: