Amazon CodeCatalyst is no longer open to new customers. Existing customers can continue to use the service as normal. For more information, see [How to migrate from CodeCatalyst](migration.md). # Deploying an CloudFormation stack This section describes how to deploy a AWS CloudFormation stack using a CodeCatalyst workflow. To accomplish this, you must add the **Deploy CloudFormation stack** action to your workflow. The action deploys a CloudFormation stack of resources into AWS based on a template that you provide. The template can be a: + CloudFormation template – For more information, see [Working with CloudFormation templates](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/template-guide.html). + AWS SAM template – For more information, see [AWS Serverless Application Model (AWS SAM) specification](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-specification.html). **Note** To use a AWS SAM template, you must first package your AWS SAM application using the `[sam package](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-cli-command-reference-sam-package.html)` operation. For a tutorial that shows you how to do this packaging automatically as part of a Amazon CodeCatalyst workflow, see [Tutorial: Deploy a serverless application](deploy-tut-lambda.md). If the stack already exists, the action runs the CloudFormation `[CreateChangeSet](https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_CreateChangeSet.html)` operation, and then the `[ExecuteChangeSet](https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_ExecuteChangeSet.html)` operation. The action then waits for the changes to be deployed and marks itself as either succeeded for failed, depending on the results. Use the **Deploy CloudFormation stack** action if you already have an CloudFormation or AWS SAM template that contains resources you'd like to deploy, or you plan on generating one automatically as part of a workflow [build action](build-add-action.md) using tools like AWS SAM and [AWS Cloud Development Kit (AWS CDK)](https://docs.aws.amazon.com/cdk/latest/guide/home.html). There are no restrictions on the template you can use—whatever you can author in CloudFormation or AWS SAM you can use with the **Deploy CloudFormation stack** action. **Tip** For a tutorial that shows you how to deploy a serverless application using the **Deploy CloudFormation stack** action, see [Tutorial: Deploy a serverless application](deploy-tut-lambda.md). **Topics** + [Runtime image used by the 'Deploy CloudFormation stack' action](#deploy-action-cfn-runtime) + [Tutorial: Deploy a serverless application](deploy-tut-lambda.md) + [Adding the 'Deploy CloudFormation stack' action](deploy-action-cfn-adding.md) + [Configuring rollbacks](deploy-consumption-enable-alarms.md) + ['Deploy CloudFormation stack' variables](deploy-action-cfn-variables.md) + ['Deploy CloudFormation stack' action YAML](deploy-action-ref-cfn.md) ## Runtime image used by the 'Deploy CloudFormation stack' action The **Deploy CloudFormation stack** action runs on a [November 2022 image](build-images.md#build.previous-image). For more information, see [Active images](build-images.md#build-curated-images). # 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)](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/what-is-sam.html), which is an extension of [CloudFormation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html). **Topics** + [Prerequisites](#deploy-tut-lambda-cfn-prereqs) + [Step 1: Create a source repository](#deploy-tut-lambda-cfn-source) + [Step 2: Create AWS roles](#deploy-tut-lambda-cfn-roles) + [Step 3: Add AWS roles to CodeCatalyst](#deploy-tut-lambda-cfn-roles-add) + [Step 4: Create an Amazon S3 bucket](#deploy-tut-lambda-cfn-s3) + [Step 5: Add source files](#deploy-tut-lambda-cfn-files) + [Step 6: Create and run a workflow](#deploy-tut-lambda-cfn-workflow) + [Step 7: Make a change](#deploy-tut-lambda-cfn-change) + [Clean up](#deploy-tut-lambda-cfn-clean-up) ## Prerequisites Before you begin: + You need a CodeCatalyst **space** with a connected AWS account. For more information, see [Creating a space](spaces-create.md). + 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](projects-create.md#projects-create-empty). + 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](deploy-environments.md). ## 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](source-repositories-create.md). **To create a source repository** 1. In CodeCatalyst, in the navigation pane, choose **Code**, and then choose **Source repositories**. 1. Choose **Add repository**, and then choose **Create repository**. 1. In **Repository name**, enter: ``` codecatalyst-cfn-source-repository ``` 1. 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](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) 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](ipa-iam-roles.md#ipa-iam-roles-service-create). 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](https://docs.aws.amazon.com/lambda/latest/dg/lambda-intro-execution-role.html) 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** 1. Create a policy for the role, as follows: 1. Sign in to AWS. 1. Open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/). 1. In the navigation pane, choose **Policies**. 1. Choose **Create policy**. 1. Choose the **JSON** tab. 1. Delete the existing code. 1. 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": "*" ``` 1. Choose **Next: Tags**. 1. Choose **Next: Review**. 1. In **Name**, enter: ``` codecatalyst-deploy-policy ``` 1. Choose **Create policy**. You have now created a permissions policy. 1. Create the deploy role, as follows: 1. In the navigation pane, choose **Roles**, and then choose **Create role**. 1. Choose **Custom trust policy**. 1. Delete the existing custom trust policy. 1. Add the following custom trust policy: 1. Choose **Next**. 1. In **Permissions policies**, search for `codecatalyst-deploy-policy` and select its check box. 1. Choose **Next**. 1. For **Role name**, enter: ``` codecatalyst-deploy-role ``` 1. For **Role description**, enter: ``` CodeCatalyst deploy role ``` 1. Choose **Create role**. You have now created a deploy role with a trust policy and permissions policy. 1. Obtain the deploy role ARN, as follows: 1. In the navigation pane, choose **Roles**. 1. In the search box, enter the name of the role you just created (`codecatalyst-deploy-role`). 1. Choose the role from the list. The role's **Summary** page appears. 1. 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** 1. Create a policy for the role, as follows: 1. Sign in to AWS. 1. Open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/). 1. In the navigation pane, choose **Policies**. 1. Choose **Create policy**. 1. Choose the **JSON** tab. 1. Delete the existing code. 1. 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": "*" ``` 1. Choose **Next: Tags**. 1. Choose **Next: Review**. 1. In **Name**, enter: ``` codecatalyst-build-policy ``` 1. Choose **Create policy**. You have now created a permissions policy. 1. Create the build role, as follows: 1. In the navigation pane, choose **Roles**, and then choose **Create role**. 1. Choose **Custom trust policy**. 1. Delete the existing custom trust policy. 1. Add the following custom trust policy: 1. Choose **Next**. 1. In **Permissions policies**, search for `codecatalyst-build-policy` and select its check box. 1. Choose **Next**. 1. For **Role name**, enter: ``` codecatalyst-build-role ``` 1. For **Role description**, enter: ``` CodeCatalyst build role ``` 1. Choose **Create role**. You have now created a build role with a trust policy and permissions policy. 1. Obtain the build role ARN, as follows: 1. In the navigation pane, choose **Roles**. 1. In the search box, enter the name of the role you just created (`codecatalyst-build-role`). 1. Choose the role from the list. The role's **Summary** page appears. 1. 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** 1. Sign in to AWS using the account where you want to deploy your stack. 1. Open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/). 1. Create the stack role as follows: 1. In the navigation pane, choose **Roles**. 1. Choose **Create role**. 1. Choose **AWS service**. 1. In the **Use case** section, choose **CloudFormation** from the drop-down list. 1. Select the **CloudFormation** radio button. 1. At the bottom, choose **Next**. 1. 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\$1FullAccess** + **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](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-permissions.html) in the *AWS Serverless Application Model Developer Guide*. 1. Choose **Next**. 1. For **Role name**, enter: ``` codecatalyst-stack-role ``` 1. Choose **Create role**. 1. Obtain the stack role's ARN, as follows: 1. In the navigation pane, choose **Roles**. 1. In the search box, enter the name of the role you just created (`codecatalyst-stack-role`). 1. Choose the role from the list. 1. In the **Summary** section, copy the **ARN** value. You need it later. You have now created the stack role with the appropriate permissions, and you have obtained its ARN. ## Step 3: Add AWS roles to CodeCatalyst In this step, you add the build role (`codecatalyst-build-role`) and deploy role (`codecatalyst-deploy-role`) to the CodeCatalyst account connection in your space. **Note** You don't need to add the stack role (`codecatalyst-stack-role`) to the connection. This is because the stack role is used by *CloudFormation* (not CodeCatalyst), *after* a connection is already established between CodeCatalyst and AWS using the deploy role. Since the stack role is not used by CodeCatalyst to gain access to AWS, it does not need to be associated with an account connection. **To add build and deploy roles to your account connection** 1. In CodeCatalyst, navigate to your space. 1. Choose **AWS accounts**. A list of account connections appears. 1. Choose the account connection that represents the AWS account where you created your build and deploy roles. 1. Choose **Manage roles from AWS management console**. The **Add IAM role to Amazon CodeCatalyst space** page appears. You might need to sign in to access the page. 1. Select **Add an existing role you have created in IAM**. A drop-down list appears. The list displays all IAM roles with a trust policy that includes the `codecatalyst-runner.amazonaws.com` and `codecatalyst.amazonaws.com` service principals. 1. In the drop-down list, choose `codecatalyst-build-role`, and choose **Add role**. 1. Choose **Add IAM role**, choose **Add an existing role you have created in IAM**, and in the drop-down list, choose `codecatalyst-deploy-role`. Choose **Add role**. You have now added the build and deploy roles to your space. 1. Copy the value of the **Amazon CodeCatalyst display name**. You'll need this value later, when creating your workflow. ## Step 4: Create an Amazon S3 bucket In this step, you create an Amazon S3 bucket where you store your serverless application's deployment package .zip file. **To create an Amazon S3 bucket** 1. Open the Amazon S3 console at [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/). 1. In the main pane, choose **Create bucket**. 1. For **Bucket name**, enter: ``` codecatalyst-cfn-s3-bucket ``` 1. For **AWS Region**, choose a Region. This tutorial assumes you chose **US West (Oregon) us-west-2**. For information about Regions supported by Amazon S3, see [Amazon Simple Storage Service endpoints and quotas](https://docs.aws.amazon.com/general/latest/gr/s3.html) in the *AWS General Reference*. 1. At the bottom of the page, choose **Create bucket**. You have now created a bucket called **codecatalyst-cfn-s3-bucket** in the US West (Oregon) us-west-2 Region. ## Step 5: Add source files In this step, you add several application source files to your CodeCatalyst source repository. The `hello-world` folder contains the application files that you'll deploy. The `tests` folder contains unit tests. The folder structure is as follows: ``` . |— hello-world | |— tests | |— unit | |— test-handler.js | |— app.js |— .npmignore |— package.json |— sam-template.yml |— setup-sam.sh ``` ### .npmignore file The `.npmignore` file indicates which files and folders npm should exclude from the application package. In this tutorial, npm excludes the `tests` folder because it is not part of the application. **To add the .npmignore file** 1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/). 1. Choose your project, `codecatalyst-cfn-project` 1. In the navigation pane, choose **Code**, and then choose **Source repositories**. 1. From the list of source repositories, choose your repository, `codecatalyst-cfn-source-repository`. 1. In **Files**, choose **Create file**. 1. For **File name**, enter: ``` .npmignore ``` 1. In the text box, enter the following code: ``` tests/* ``` 1. Choose **Commit**, and then choose **Commit** again. You have now created a file called `.npmignore` in the root of your repository. ### package.json file The `package.json` file contains important metadata about your Node project such as the project name, version number, description, dependencies, and other details that describe how to interact with and run your application. The `package.json` in this tutorial includes a list of dependencies and a `test` script. The test script does the following: + Using [mocha](https://mochajs.org/), the test script runs the unit tests specified in `hello-world/tests/unit/` and writes the results to a `junit.xml` file using the [xunit]() reporter. + Using [Istanbul (nyc)](https://istanbul.js.org/), the test script generates a code coverage report (`clover.xml`) using the [clover](https://openclover.org/doc/manual/4.2.0/general--about-openclover.html) reporter. For more information, see [Using alternative reporters](https://istanbul.js.org/docs/advanced/alternative-reporters/#clover) in the Istanbul documentation. **To add the package.json file** 1. In your repository, in **Files**, choose **Create file**. 1. For **File name**, enter: ``` package.json ``` 1. In the text box, enter the following code: ``` { "name": "hello_world", "version": "1.0.0", "description": "hello world sample for NodeJS", "main": "app.js", "repository": "https://github.com/awslabs/aws-sam-cli/tree/develop/samcli/local/init/templates/cookiecutter-aws-sam-hello-nodejs", "author": "SAM CLI", "license": "MIT", "dependencies": { "axios": "^0.21.1", "nyc": "^15.1.0" }, "scripts": { "test": "nyc --reporter=clover mocha hello-world/tests/unit/ --reporter xunit --reporter-option output=junit.xml" }, "devDependencies": { "aws-sdk": "^2.815.0", "chai": "^4.2.0", "mocha": "^8.2.1" } } ``` 1. Choose **Commit**, and then choose **Commit** again. You have now added a file called `package.json` to the root of the repository. ### sam-template.yml file The `sam-template.yml` file contains the instructions for deploying the Lambda function and API Gateway and configuring them together. It follows the [AWS Serverless Application Model template specification](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-specification.html), which extends the CloudFormation template specification. You use an AWS SAM template in this tutorial instead of a regular CloudFormation template because AWS SAM offers a helpful [AWS::Serverless::Function](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-resource-function.html) resource type. This type performs much behind-the-scenes configuration that you normally have to write out to use the basic CloudFormation syntax. For example, the `AWS::Serverless::Function` creates a Lambda function, Lambda execution role, and event source mappings that start the function. You have to code all of this if you want to write it using basic CloudFormation. Although this tutorial uses a pre-written template, you can generate one as part of your workflow using a build action. For more information, see [Deploying an CloudFormation stack](deploy-action-cfn.md). **To add the sam-template.yml file** 1. In your repository, in **Files**, choose **Create file**. 1. For **File name**, enter: ``` sam-template.yml ``` 1. In the text box, enter the following code: ``` AWSTemplateFormatVersion: '2010-09-09' Transform: AWS::Serverless-2016-10-31 Description: > serverless-api Sample SAM Template for serverless-api # More info about Globals: https://github.com/awslabs/serverless-application-model/blob/master/docs/globals.rst Globals: Function: Timeout: 3 Resources: HelloWorldFunction: Type: AWS::Serverless::Function # For details on this resource type, see https://github.com/awslabs/serverless-application-model/blob/master/versions/2016-10-31.md#awsserverlessfunction Properties: CodeUri: hello-world/ Handler: app.lambdaHandler Runtime: nodejs12.x Events: HelloWorld: Type: Api # For details on this event source type, see https://github.com/awslabs/serverless-application-model/blob/master/versions/2016-10-31.md#api Properties: Path: /hello Method: get Outputs: # ServerlessRestApi is an implicit API created out of the events key under Serverless::Function # Find out about other implicit resources you can reference within AWS SAM at # https://github.com/awslabs/serverless-application-model/blob/master/docs/internals/generated_resources.rst#api HelloWorldApi: Description: "API Gateway endpoint URL for the Hello World function" Value: !Sub "https://${ServerlessRestApi}.execute-api.${AWS::Region}.amazonaws.com/Prod/hello/" HelloWorldFunction: Description: "Hello World Lambda function ARN" Value: !GetAtt HelloWorldFunction.Arn HelloWorldFunctionIamRole: Description: "Implicit Lambda execution role created for the Hello World function" Value: !GetAtt HelloWorldFunctionRole.Arn ``` 1. Choose **Commit**, and then choose **Commit** again. You have now added a file called `sam-template.yml` under the root folder of your repository. ### setup-sam.sh file The `setup-sam.sh` file contains the instructions for downloading and installing the AWS SAM CLI utility. The workflow uses this utility to package the `hello-world` source. **To add the setup-sam.sh file** 1. In your repository, in **Files**, choose **Create file**. 1. For **File name**, enter: ``` setup-sam.sh ``` 1. In the text box, enter the following code: ``` #!/usr/bin/env bash echo "Setting up sam" yum install unzip -y curl -LO https://github.com/aws/aws-sam-cli/releases/latest/download/aws-sam-cli-linux-x86_64.zip unzip -qq aws-sam-cli-linux-x86_64.zip -d sam-installation-directory ./sam-installation-directory/install; export AWS_DEFAULT_REGION=us-west-2 ``` In the preceding code, replace *us-west-2* with your AWS Region. 1. Choose **Commit**, and then choose **Commit** again. You have now added a file called `setup-sam.sh` to the root of the repository. ### app.js file The `app.js` contains the Lambda function code. In this tutorial, the code returns the text `hello world`. **To add the app.js file** 1. In your repository, in **Files**, choose **Create file**. 1. For **File name**, enter: ``` hello-world/app.js ``` 1. In the text box, enter the following code: ``` // const axios = require('axios') // const url = 'http://checkip.amazonaws.com/'; let response; /** * * Event doc: https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-lambda-proxy-integrations.html#api-gateway-simple-proxy-for-lambda-input-format * @param {Object} event - API Gateway Lambda Proxy Input Format * * Context doc: https://docs.aws.amazon.com/lambda/latest/dg/nodejs-prog-model-context.html * @param {Object} context * * Return doc: https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-lambda-proxy-integrations.html * @returns {Object} object - API Gateway Lambda Proxy Output Format * */ exports.lambdaHandler = async (event, context) => { try { // const ret = await axios(url); response = { 'statusCode': 200, 'body': JSON.stringify({ message: 'hello world', // location: ret.data.trim() }) } } catch (err) { console.log(err); return err; } return response }; ``` 1. Choose **Commit**, and then choose **Commit** again. You have now created a folder called `hello-world` and a file called `app.js`. ### test-handler.js file The `test-handler.js` file contains unit tests for the Lambda function. **To add the test-handler.js file** 1. In your repository, in **Files**, choose **Create file**. 1. For **File name**, enter: ``` hello-world/tests/unit/test-handler.js ``` 1. In the text box, enter the following code: ``` 'use strict'; const app = require('../../app.js'); const chai = require('chai'); const expect = chai.expect; var event, context; describe('Tests index', function () { it('verifies successful response', async () => { const result = await app.lambdaHandler(event, context) expect(result).to.be.an('object'); expect(result.statusCode).to.equal(200); expect(result.body).to.be.an('string'); let response = JSON.parse(result.body); expect(response).to.be.an('object'); expect(response.message).to.be.equal("hello world"); // expect(response.location).to.be.an("string"); }); }); ``` 1. Choose **Commit**, and then choose **Commit** again. You have now added a file called `test-handler.js` under the `hello-world/tests/unit` folder. You have now added all your source files. Take a moment to double-check your work and make sure you placed all the files in the correct folders. The folder structure is as follows: ``` . |— hello-world | |— tests | |— unit | |— test-handler.js | |— app.js |— .npmignore |— README.md |— package.json |— sam-template.yml |— setup-sam.sh ``` ## Step 6: Create and run a workflow In this step, you create a workflow that packages your Lambda source code and deploys it. The workflow consists of the following building blocks that run sequentially: + A trigger – This trigger starts the workflow run automatically when you push a change to your source repository. For more information about triggers, see [Starting a workflow run automatically using triggers](workflows-add-trigger.md). + A test action (`Test`) – On trigger, this action installs [Node package manager (npm)](https://www.npmjs.com/), and then runs the `npm run test` command. This command tells npm to run the `test` script defined in the `package.json` file. The `test` script, in turn, runs the unit tests and generates two reports: a test report (`junit.xml`) and a code coverage report (`clover.xml`). For more information, see [package.json file](#deploy-tut-lambda-cfn-files-package-json). Next, the test action transforms the XML reports into CodeCatalyst reports and displays them in the CodeCatalyst console, under the **Reports** tab of the test action. For more information about the test action, see [Testing with workflowsTesting with workflows](test-workflow-actions.md). + A build action (`BuildBackend`) – On completion of the test action, the build action downloads and installs the AWS SAM CLI, packages the `hello-world` source, and copies the package to your Amazon S3 bucket, where the Lambda service expects it to be. The action also outputs a new AWS SAM template file called `sam-template-packaged.yml` and places it in an output artifact called `buildArtifact`. For more information about the build action, see [Building with workflows](build-workflow-actions.md). + A deploy action (`DeployCloudFormationStack`) – On completion of the build action, the deploy action looks for the output artifact generated by the build action (`buildArtifact`), finds the AWS SAM template inside of it, and then runs the template. The AWS SAM template creates a stack that deploys the serverless application. **To create a workflow** 1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**. 1. Choose **Create workflow**. 1. For **Source repository**, choose `codecatalyst-cfn-source-repository`. 1. For **Branch**, choose `main`. 1. Choose **Create**. 1. Delete the YAML sample code. 1. Add the following YAML code: **Note** In the YAML code that follows, you can omit the `Connections:` sections if you want. If you omit these sections, you must ensure that the role specified in the **Default IAM role** field in your environment includes the permissions and trust policies of both roles described in [Step 2: Create AWS roles](#deploy-tut-lambda-cfn-roles). For more information about setting up an environment with a default IAM role, see [Creating an environment](deploy-environments-creating-environment.md). ``` Name: codecatalyst-cfn-workflow SchemaVersion: 1.0 Triggers: - Type: PUSH Branches: - main Actions: Test: Identifier: aws/managed-test@v1 Inputs: Sources: - WorkflowSource Outputs: Reports: CoverageReport: Format: CLOVERXML IncludePaths: - "coverage/*" TestReport: Format: JUNITXML IncludePaths: - junit.xml Configuration: Steps: - Run: npm install - Run: npm run test BuildBackend: Identifier: aws/build@v1 DependsOn: - Test Environment: Name: codecatalyst-cfn-environment Connections: - Name: codecatalyst-account-connection Role: codecatalyst-build-role Inputs: Sources: - WorkflowSource Configuration: Steps: - Run: . ./setup-sam.sh - Run: sam package --template-file sam-template.yml --s3-bucket codecatalyst-cfn-s3-bucket --output-template-file sam-template-packaged.yml --region us-west-2 Outputs: Artifacts: - Name: buildArtifact Files: - "**/*" DeployCloudFormationStack: Identifier: aws/cfn-deploy@v1 DependsOn: - BuildBackend Environment: Name: codecatalyst-cfn-environment Connections: - Name: codecatalyst-account-connection Role: codecatalyst-deploy-role Inputs: Artifacts: - buildArtifact Sources: [] Configuration: name: codecatalyst-cfn-stack region: us-west-2 role-arn: arn:aws:iam::111122223333:role/StackRole template: ./sam-template-packaged.yml capabilities: CAPABILITY_IAM,CAPABILITY_AUTO_EXPAND ``` In the preceding code, replace: + Both instances of *codecatalyst-cfn-environment* with the name of your environment. + Both instances of *codecatalyst-account-connection* with the display name of your account connection. The display name might be a number. For more information, see [Step 3: Add AWS roles to CodeCatalyst](#deploy-tut-lambda-cfn-roles-add). + *codecatalyst-build-role* with the name of the build role that you created in [Step 2: Create AWS roles](#deploy-tut-lambda-cfn-roles). + *codecatalyst-cfn-s3-bucket* with the name of the Amazon S3 bucket you created in [Step 4: Create an Amazon S3 bucket](#deploy-tut-lambda-cfn-s3). + Both instances of *us-west-2* with the Region where your Amazon S3 bucket resides (first instance) and where your stack will be deployed (second instance). These Regions can be different. This tutorial assumes that both Regions are set to `us-west-2`. For details about Regions supported by Amazon S3 and CloudFormation, see [Service endpoints and quotas](https://docs.aws.amazon.com/general/latest/gr/aws-service-information.html) in the *AWS General Reference*. + *codecatalyst-deploy-role* with the name of the deploy role that you created in [Step 2: Create AWS roles](#deploy-tut-lambda-cfn-roles). + *codecatalyst-cfn-environment* with the name of the environment that you created in [Prerequisites](#deploy-tut-lambda-cfn-prereqs). + *arn:aws:iam::111122223333:role/StackRole* with the Amazon Resource Name (ARN) of the stack role that you created in [Step 2: Create AWS roles](#deploy-tut-lambda-cfn-roles). **Note** If you decided not to create build, deploy, and stack roles, replace *codecatalyst-build-role*, *codecatalyst-deploy-role*, and *arn:aws:iam::111122223333:role/StackRole* with the name or ARN of the `CodeCatalystWorkflowDevelopmentRole-spaceName` role. For more information about this role, see [Step 2: Create AWS roles](#deploy-tut-lambda-cfn-roles). For information about the properties in the code shown previously, see the ['Deploy CloudFormation stack' action YAML](deploy-action-ref-cfn.md). 1. (Optional) Choose **Validate** to make sure the YAML code is valid before committing. 1. Choose **Commit**. 1. On the **Commit workflow** dialog box, enter the following: 1. For **Workflow file name**, keep the default, `codecatalyst-cfn-workflow`. 1. For **Commit message**, enter: ``` add initial workflow file ``` 1. For **Repository**, choose **codecatalyst-cfn-source-repository**. 1. For **Branch name**, choose **main**. 1. Choose **Commit**. You have now created a workflow. A workflow run starts automatically because of the trigger defined at the top of the workflow. Specifically, when you committed (and pushed) the `codecatalyst-cfn-workflow.yaml` file to your source repository, the trigger started the workflow run. **To view the workflow run in progress** 1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**. 1. Choose the workflow you just created: `codecatalyst-cfn-workflow`. 1. Choose the **Runs** tab. 1. In the **Run ID** column, choose the run ID. 1. Choose **Test** to see the tests progress. 1. Choose **BuildBackend** to see the build progress. 1. Choose **DeployCloudFormationStack** to see the deployment progress. For more information about viewing run details, see [Viewing workflow run status and details](workflows-view-run.md). 1. When the **DeployCloudFormationStack** action finishes, do the following: + If the workflow run succeeded, go to the next procedure. + If the workflow run failed on the **Test** or **BuildBackend** action, choose **Logs** to troubleshoot the issue. + If the workflow run failed on the **DeployCloudFormationStack** action, choose the deploy action, and then choose the **Summary** tab. Scroll to the **CloudFormation events** section to view the detailed error message. If a rollback occurred, delete the `codecatalyst-cfn-stack` stack through the CloudFormation console in AWS before re-running the workflow. **To verify the deployment** 1. After a successful deployment, choose **Variables (7)** from the horizontal menu bar near the top. (Do not choose **Variables** in the pane on the right.) 1. Next to **HelloWorldApi**, paste the `https://` URL into a browser. A **hello world** JSON message from the Lambda function is displayed, indicating that the workflow deployed and configured the Lambda function and API Gateway successfully. **Tip** You can have CodeCatalyst display this URL in the workflow diagram with a few small configurations. For more information, see [Displaying the app URL in the workflow diagram](deploy-app-url.md). **To verify unit test results and code coverage** 1. In the workflow diagram, choose **Test**, and then choose **Reports**. 1. Choose **TestReport** to view the unit test results, or choose **CoverageReport** to view the code coverage details of the files being tested, in this case, `app.js` and `test-handler.js`. **To verify deployed resources** 1. Sign in to the AWS Management Console and open the API Gateway console at [https://console.aws.amazon.com/apigateway/](https://console.aws.amazon.com/apigateway/). 1. Observe the **codecatalyst-cfn-stack** API that the AWS SAM template created. The API name comes from the `Configuration/name` value in the workflow definition file (`codecatalyst-cfn-workflow.yaml`). 1. Open the AWS Lambda console at [https://console.aws.amazon.com/lambda/](https://console.aws.amazon.com/lambda/). 1. In the navigation pane, choose **Functions**. 1. Choose your Lambda function, `codecatalyst-cfn-stack-HelloWorldFunction-string`. 1. You can see how the API Gateway is a trigger for the function. This integration was automatically configured by the AWS SAM `AWS::Serverless::Function` resource type. ## Step 7: Make a change In this step, you make a change to your Lambda source code and commit it. This commit starts a new workflow run. This run deploys the new Lambda function in a blue-green scheme that uses the default traffic shifting configuration specified in the Lambda console. **To make a change to your Lambda source** 1. In CodeCatalyst, navigate to your project. 1. In the navigation pane, choose **Code**, and then choose **Source repositories**. 1. Choose your source repository `codecatalyst-cfn-source-repository`. 1. Change the application file: 1. Choose the `hello-world` folder. 1. Choose the `app.js` file. 1. Choose **Edit**. 1. On line 23, change `hello world` to **Tutorial complete\$1**. 1. Choose **Commit**, and then choose **Commit** again. The commit causes a workflow run to start. This run will fail because you haven't updated the unit tests to reflect the name change. 1. Update the unit tests: 1. Choose `hello-world\tests\unit\test-handler.js`. 1. Choose **Edit**. 1. On line 19, change `hello world` to **Tutorial complete\$1**. 1. Choose **Commit**, and then choose **Commit** again. The commit causes another workflow run to start. This run will succeed. 1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**. 1. Choose `codecatalyst-cfn-workflow`, and then choose **Runs**. 1. Choose the run ID of the latest run. It should still be in progress. 1. Choose **Test**, **BuildBackend**, and **DeployCloudFormationStack** to see the workflow run progress. 1. When the workflow finishes, choose **Variables (7)** near the top. 1. Next to **HelloWorldApi**, paste the `https://` URL into a browser. A `Tutorial complete!` message appears in the browser, indicating that your new application was deployed successfully. ## Clean up Clean up the files and services used in this tutorial to avoid being charged for them. **To clean up in the CodeCatalyst console** 1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/). 1. Delete `codecatalyst-cfn-workflow`. 1. Delete `codecatalyst-cfn-environment`. 1. Delete `codecatalyst-cfn-source-repository`. 1. Delete `codecatalyst-cfn-project`. **To clean up in the AWS Management Console** 1. Clean up in CloudFormation, as follows: 1. Open the CloudFormation console at [https://console.aws.amazon.com/cloudformation](https://console.aws.amazon.com/cloudformation/). 1. Delete the `codecatalyst-cfn-stack`. Deleting the stack removes all tutorial resources from the API Gateway and Lambda services. 1. Clean up in Amazon S3, as follows: 1. Open the Amazon S3 console at [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/). 1. Choose the `codecatalyst-cfn-s3-bucket`. 1. Delete the bucket contents. 1. Delete the bucket. 1. Clean up in IAM, as follows: 1. Open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/). 1. Delete the `codecatalyst-deploy-policy`. 1. Delete the `codecatalyst-build-policy`. 1. Delete the `codecatalyst-stack-policy`. 1. Delete the `codecatalyst-deploy-role`. 1. Delete the `codecatalyst-build-role`. 1. Delete the `codecatalyst-stack-role`. In this tutorial, you learned how to deploy a serverless application as a CloudFormation stack using a CodeCatalyst workflow and a **Deploy CloudFormation stack** action. # Adding the 'Deploy CloudFormation stack' action Use the following instructions to add the **Deploy CloudFormation stack** action to your workflow. ------ #### [ Visual ] **To add the 'Deploy CloudFormation stack' action using the visual editor** 1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/). 1. Choose your project. 1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**. 1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status. 1. Choose **Edit**. 1. Choose **Visual**. 1. At the top-left, choose **\$1 Actions** to open the action catalog. 1. From the drop-down list, choose **Amazon CodeCatalyst**. 1. Search for the **Deploy CloudFormation stack** action, and do one of the following: + Choose the plus sign (**\$1**) to add the action to the workflow diagram and open its configuration pane. Or + Choose **Deploy CloudFormation stack**. The action details dialog box appears. On this dialog box: + (Optional) Choose **Download** to [view the action's source code](workflows-view-source.md#workflows-view-source.title). + Choose **Add to workflow** to add the action to the workflow diagram and open its configuration pane. 1. In the **Inputs** and **Configuration** tabs, complete the fields according to your needs. For a description of each field, see the ['Deploy CloudFormation stack' action YAML](deploy-action-ref-cfn.md). This reference provides detailed information about each field (and corresponding YAML property value) as it appears in both the YAML and visual editors. 1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing. 1. Choose **Commit**, enter a commit message, and choose **Commit** again. ------ #### [ YAML ] **To add the 'Deploy CloudFormation stack' action using the YAML editor** 1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/). 1. Choose your project. 1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**. 1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status. 1. Choose **Edit**. 1. Choose **YAML**. 1. At the top-left, choose **\$1 Actions** to open the action catalog. 1. From the drop-down list, choose **Amazon CodeCatalyst**. 1. Search for the **Deploy CloudFormation stack** action, and do one of the following: + Choose the plus sign (**\$1**) to add the action to the workflow diagram and open its configuration pane. Or + Choose **Deploy CloudFormation stack**. The action details dialog box appears. On this dialog box: + (Optional) Choose **Download** to [view the action's source code](workflows-view-source.md#workflows-view-source.title). + Choose **Add to workflow** to add the action to the workflow diagram and open its configuration pane. 1. Modify the properties in the YAML code according to your needs. An explanation of each available property is provided in the ['Deploy CloudFormation stack' action YAML](deploy-action-ref-cfn.md). 1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing. 1. Choose **Commit**, enter a commit message, and choose **Commit** again. ------ # Configuring rollbacks By default, if the **Deploy CloudFormation stack** action fails, it will cause CloudFormation to roll back the stack to the last known stable state. You can change the behavior so that rollbacks occur not only when the action fails, but also when a specified Amazon CloudWatch alarm occurs. For more information about CloudWatch alarms, see [Using Amazon CloudWatch alarms](https://docs.aws.amazon.com/) in the *Amazon CloudWatch User Guide*. You can also change the default behavior so that CloudFormation does not roll back the stack when the action fails. Use the following instructions to configure rollbacks. **Note** You cannot start a rollback manually. ------ #### [ Visual ] **Before you begin** 1. Make sure you have a [workflow](workflow.md) that includes a functioning **Deploy CloudFormation stack** action. For more information, see [Deploying an CloudFormation stack](deploy-action-cfn.md). 1. In the role specified in the **Stack role - optional** field of the **Deploy CloudFormation stack** action, make sure to include the **CloudWatchFullAccess** permission. For information about creating this role with the appropriate permissions, see [Step 2: Create AWS roles](deploy-tut-lambda.md#deploy-tut-lambda-cfn-roles). **To configure rollback alarms for the 'Deploy CloudFormation stack' action** 1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/). 1. Choose your project. 1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**. 1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status. 1. Choose **Edit**. 1. Choose **Visual**. 1. Choose your **Deploy CloudFormation stack** action. 1. In the details pane, choose **Configuration**. 1. At the bottom, expand **Advanced**. 1. Under **Monitor alarm ARNs**, choose **Add alarm**. 1. Enter information into the following fields. + **Alarm ARN** Specify the Amazon Resource Name (ARN) of an Amazon CloudWatch alarm to use as a rollback trigger. For example, `arn:aws:cloudwatch::123456789012:alarm/MyAlarm`. You can have a maximum of five rollback triggers. **Note** If you specify a CloudWatch alarm ARN, you'll also need to configure additional permissions to enable the action to access CloudWatch. For more information, see [Configuring rollbacks](#deploy-consumption-enable-alarms). + **Monitoring time** Specify an amount of time, from 0 to 180 minutes, during which CloudFormation monitors the specified alarms. Monitoring begins *after* all the stack resources have been deployed. If the alarm occurs within the specified monitoring time, then the deployment fails, and CloudFormation rolls back the entire stack operation. Default: 0. CloudFormation only monitors alarms while the stack resources are being deployed, not after. ------ #### [ YAML ] **To configure rollback triggers for the 'Deploy CloudFormation stack' action** 1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/). 1. Choose your project. 1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**. 1. Choose the name of a workflow that includes the **Deploy CloudFormation stack** action. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status. 1. Choose **Edit**. 1. Choose **YAML**. 1. Add the `monitor-alarm-arns` and `monitor-timeout-in-minutes` properties in the YAML code to add rollback triggers. For an explanation of each property, see ['Deploy CloudFormation stack' action YAML](deploy-action-ref-cfn.md). 1. In the role specified in the `role-arn` property of the **Deploy CloudFormation stack** action, make sure to include the **CloudWatchFullAccess** permission. For information about creating this role with the appropriate permissions, see [Step 2: Create AWS roles](deploy-tut-lambda.md#deploy-tut-lambda-cfn-roles). ------ ------ #### [ Visual ] **To turn off rollbacks for the 'Deploy CloudFormation stack' action** 1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/). 1. Choose your project. 1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**. 1. Choose the name of a workflow that includes the **Deploy CloudFormation stack** action. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status. 1. Choose **Edit**. 1. Choose **Visual**. 1. Choose your **Deploy CloudFormation stack** action. 1. In the details pane, choose **Configuration**. 1. At the bottom, expand **Advanced**. 1. Turn on **Disable rollback**. ------ #### [ YAML ] **To turn off rollbacks for the 'Deploy CloudFormation stack' action** 1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/). 1. Choose your project. 1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**. 1. Choose the name of a workflow that includes the **Deploy CloudFormation stack** action. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status. 1. Choose **Edit**. 1. Choose **YAML**. 1. Add the `disable-rollback: 1` property in the YAML code to stop rollbacks. For an explanation of this property, see ['Deploy CloudFormation stack' action YAML](deploy-action-ref-cfn.md). ------ # 'Deploy CloudFormation stack' variables The **Deploy CloudFormation stack** action produces and sets the following variables at run time. These are known as *predefined variables*. For information about referencing these variables in a workflow, see [Using predefined variables](workflows-using-predefined-variables.md). | Key | Value | | --- | --- | | deployment-platform | The name of the deployment platform. Hardcoded to `AWS:CloudFormation`. | | region | The region code of the AWS Region that was deployed to during the workflow run. Example: `us-west-2` | | stack-id | The Amazon Resource Name (ARN) of the deployed stack. Example: `arn:aws:cloudformation:us-west-2:111122223333:stack/codecatalyst-cfn-stack/6aad4380-100a-11ec-a10a-03b8a84d40df` | # 'Deploy CloudFormation stack' action YAML The following is the YAML definition of the **Deploy CloudFormation stack** action. To learn how to use this action, see [Deploying an CloudFormation stack](deploy-action-cfn.md). This action definition exists as a section within a broader workflow definition file. For more information about this file, see [Workflow YAML definition](workflow-reference.md). **Note** Most of the YAML properties that follow have corresponding UI elements in the visual editor. To look up a UI element, use **Ctrl\$1F**. The element will be listed with its associated YAML property. ``` # The workflow definition starts here. # See Top-level properties for details. Name: MyWorkflow SchemaVersion: 1.0 Actions: # The action definition starts here. DeployCloudFormationStack: Identifier: aws/cfn-deploy@v1 DependsOn: - build-action Compute: Type: EC2 | Lambda Fleet: fleet-name Timeout: timeout-minutes Environment: Name: environment-name Connections: - Name: account-connection-name Role: DeployRole Inputs: Sources: - source-name-1 Artifacts: - CloudFormation-artifact Configuration: name: stack-name region: us-west-2 template: template-path role-arn: arn:aws:iam::123456789012:role/StackRole capabilities: CAPABILITY_IAM,CAPABILITY_NAMED_IAM,CAPABILITY_AUTO_EXPAND parameter-overrides: KeyOne=ValueOne,KeyTwo=ValueTwo | path-to-JSON-file no-execute-changeset: 1|0 fail-on-empty-changeset: 1|0 disable-rollback: 1|0 termination-protection: 1|0 timeout-in-minutes: minutes notification-arns: arn:aws:sns:us-east-1:123456789012:MyTopic,arn:aws:sns:us-east-1:123456789012:MyOtherTopic monitor-alarm-arns: arn:aws:cloudwatch::123456789012:alarm/MyAlarm,arn:aws:cloudwatch::123456789012:alarm/MyOtherAlarm monitor-timeout-in-minutes: minutes tags: '[{"Key":"MyKey1","Value":"MyValue1"},{"Key":"MyKey2","Value":"MyValue2"}]' ``` ## DeployCloudFormationStack (Required) Specify the name of the action. All action names must be unique within the workflow. Action names are limited to alphanumeric characters (a-z, A-Z, 0-9), hyphens (-), and underscores (\$1). Spaces are not allowed. You cannot use quotation marks to enable special characters and spaces in action names. Default: `DeployCloudFormationStack_nn`. Corresponding UI: Configuration tab/**Action display name** ## Identifier (*DeployCloudFormationStack*/**Identifier**) (Required) Identifies the action. Do not change this property unless you want to change the version. For more information, see [Specifying the action version to use](workflows-action-versions.md). Default: `aws/cfn-deploy@v1`. Corresponding UI: Workflow diagram/DeployCloudFormationStack\$1nn/**aws/cfn-deploy@v1** label ## DependsOn (*DeployCloudFormationStack*/**DependsOn**) (Optional) Specify an action, action group, or gate that must run successfully in order for this action to run. For more information about the 'depends on' functionality, see [Sequencing actions](workflows-depends-on.md). Corresponding UI: Inputs tab/**Depends on - optional** ## Compute (*DeployCloudFormationStack*/**Compute**) (Optional) The computing engine used to run your workflow actions. You can specify compute either at the workflow level or at the action level, but not both. When specified at the workflow level, the compute configuration applies to all actions defined in the workflow. At the workflow level, you can also run multiple actions on the same instance. For more information, see [Sharing compute across actions](compute-sharing.md). Corresponding UI: *none* ## Type (*DeployCloudFormationStack*/Compute/**Type**) (Required if [Compute](#deploy.action.cfn.computename) is included) The type of compute engine. You can use one of the following values: + **EC2** (visual editor) or `EC2` (YAML editor) Optimized for flexibility during action runs. + **Lambda** (visual editor) or `Lambda` (YAML editor) Optimized action start-up speeds. For more information about compute types, see [Compute types](workflows-working-compute.md#compute.types). Corresponding UI: Configuration tab/Advanced - optional/**Compute type** ## Fleet (*DeployCloudFormationStack*/Compute/**Fleet**) (Optional) Specify the machine or fleet that will run your workflow or workflow actions. With on-demand fleets, when an action starts, the workflow provisions the resources it needs, and the machines are destroyed when the action finishes. Examples of on-demand fleets: `Linux.x86-64.Large`, `Linux.x86-64.XLarge`. For more information about on-demand fleets, see [On-demand fleet properties](workflows-working-compute.md#compute.on-demand). With provisioned fleets, you configure a set of dedicated machines to run your workflow actions. These machines remain idle, ready to process actions immediately. For more information about provisioned fleets, see [Provisioned fleet properties](workflows-working-compute.md#compute.provisioned-fleets). If `Fleet` is omitted, the default is `Linux.x86-64.Large`. Corresponding UI: Configuration tab/Advanced - optional/**Compute fleet** ## Timeout (*DeployCloudFormationStack*/**Timeout**) (Optional) Specify the amount of time in minutes (YAML editor), or hours and minutes (visual editor), that the action can run before CodeCatalyst ends the action. The minimum is 5 minutes and the maximum is described in [Quotas for workflows in CodeCatalyst](workflows-quotas.md). The default timeout is the same as the maximum timeout. Corresponding UI: Configuration tab/**Timeout in minutes - optional ** ## Environment (*DeployCloudFormationStack*/**Environment**) (Required) Specify the CodeCatalyst environment to use with the action. The action connects to the AWS account and optional Amazon VPC specified in the chosen environment. The action uses the default IAM role specified in the environment to connect to the AWS account, and uses the IAM role specified in the [Amazon VPC connection](https://docs.aws.amazon.com/codecatalyst/latest/adminguide/managing-vpcs.add.html) to connect to the Amazon VPC. **Note** If the default IAM role does not have the permissions required by the action, you can configure the action to use a different role. For more information, see [Changing the IAM role of an action](deploy-environments-switch-role.md). For more information about environments, see [Deploying into AWS accounts and VPCs](deploy-environments.md) and [Creating an environment](deploy-environments-creating-environment.md). Corresponding UI: Configuration tab/**Environment** ## Name (*DeployCloudFormationStack*/Environment/**Name**) (Required if [Environment](#deploy.action.cfn.environment) is included) Specify the name of an existing environment that you want to associate with the action. Corresponding UI: Configuration tab/**Environment** ## Connections (*DeployCloudFormationStack*/Environment/**Connections**) (Optional in newer versions of the action; required in older versions) Specify the account connection to associate with the action. You can specify a maximum of one account connection under `Environment`. If you do not specify an account connection: + The action uses the AWS account connection and default IAM role specified in the environment in the CodeCatalyst console. For information about adding an account connection and default IAM role to environment, see [Creating an environment](deploy-environments-creating-environment.md). + The default IAM role must include the policies and permissions required by the action. To determine what those policies and permissions are, see the description of the **Role** property in the action's YAML definition documentation. For more information about account connections, see [Allowing access to AWS resources with connected AWS accounts](ipa-connect-account.md). For information about adding an account connection to an environment, see [Creating an environment](deploy-environments-creating-environment.md). Corresponding UI: One of the following depending on the action version: + (Newer versions) Configuration tab/Environment/What's in *my-environment*?/three dot menu/**Switch role** + (Older versions) Configuration tab/'Environment/account/role'/**AWS account connection** ## Name (*DeployCloudFormationStack*/Environment/Connections/**Name**) (Required if [Connections](#deploy.action.cfn.environment.connections) is included) Specify the name of the account connection. Corresponding UI: One of the following depending on the action version: + (Newer versions) Configuration tab/Environment/What's in *my-environment*?/three dot menu/**Switch role** + (Older versions) Configuration tab/'Environment/account/role'/**AWS account connection** ## Role (*DeployCloudFormationStack*/Environment/Connections/**Role**) (Required if [Connections](#deploy.action.cfn.environment.connections) is included) Specify the name of the IAM role that the **Deploy CloudFormation stack** action uses to access AWS and the CloudFormation service. Make sure that you have [added the role to your CodeCatalyst space](ipa-connect-account-addroles.md), and that the role includes the following policies. If you do not specify an IAM role, then the action uses the default IAM role listed in the [environment](deploy-environments.md) in the CodeCatalyst console. If you use the default role in the environment, make sure it has the following policies. + The following permissions policy: **Warning** Limit the permissions to those shown in the following policy. Using a role with broader permissions might pose a security risk. **Note** The first time the role is used, use the following wildcard in the resource policy statement and then scope down the policy with the resource name after it is available. ``` "Resource": "*" ``` + The following custom trust policy: **Note** You can use the `CodeCatalystWorkflowDevelopmentRole-spaceName` role with this action, if you'd like. For more information about this role, see [Creating the **CodeCatalystWorkflowDevelopmentRole-*spaceName*** role for your account and space](ipa-iam-roles.md#ipa-iam-roles-service-create). Understand that the `CodeCatalystWorkflowDevelopmentRole-spaceName` role has full access permissions which may pose a security risk. We recommend that you only use this role in tutorials and scenarios where security is less of a concern. Corresponding UI: One of the following depending on the action version: + (Newer versions) Configuration tab/Environment/What's in *my-environment*?/three dot menu/**Switch role** + (Older versions) Configuration tab/'Environment/account/role'/**Role** ## Inputs (*DeployCloudFormationStack*/**Inputs**) (Optional) The `Inputs` section defines the data that the `DeployCloudFormationStack` needs during a workflow run. **Note** A maximum of four inputs (one source and three artifacts) are allowed per **Deploy CloudFormation stack** action. If you need to refer to files residing in different inputs (say a source and an artifact), the source input is the primary input, and the artifact is the secondary input. References to files in secondary inputs take a special prefix to distiguish them from the primary. For details, see [Example: Referencing files in multiple artifacts](workflows-working-artifacts-ex.md#workflows-working-artifacts-ex-ref-file). Corresponding UI: **Inputs** tab ## Sources (*DeployCloudFormationStack*/Inputs/**Sources**) (Required if your CloudFormation or AWS SAM template is stored in a source repository) If your CloudFormation or AWS SAM template is stored in a source repository, specify the label of that source repository. Currently, the only supported label is `WorkflowSource`. If your CloudFormation or AWS SAM template is not contained within a source repository, it must reside in an artifact generated by another action, or in an Amazon S3 bucket. For more information about sources, see [Connecting source repositories to workflows](workflows-sources.md). Corresponding UI: Inputs tab/**Sources - optional** ## Artifacts - input (*DeployCloudFormationStack*/Inputs/**Artifacts**) (Required if your CloudFormation or AWS SAM template is stored in an [output artifact](workflows-working-artifacts-output.md) from a previous action) If the CloudFormation or AWS SAM template that you want to deploy is contained in an artifact generated by a previous action, specify that artifact here. If your CloudFormation template is not contained within an artifact, it must reside in your source repository or in an Amazon S3 bucket. For more information about artifacts, including examples, see [Sharing artifacts and files between actions](workflows-working-artifacts.md). Corresponding UI: Configuration tab/**Artifacts - optional** ## Configuration (*DeployCloudFormationStack*/**Configuration**) (Required) A section where you can define the configuration properties of the action. Corresponding UI: **Configuration** tab ## name (*DeployCloudFormationStack*/Configuration/**name**) (Required) Specify a name for the CloudFormation stack that the **Deploy CloudFormation stack** action creates or updates. Corresponding UI: Configuration tab/**Stack name** ## region (*DeployCloudFormationStack*/Configuration/**region**) (Required) Specify the AWS Region into which the stack will be deployed. For a list of Region codes, see [Regional endpoints](https://docs.aws.amazon.com/general/latest/gr/rande.html#region-names-codes). Corresponding UI: Configuration tab/**Stack region** ## template (*DeployCloudFormationStack*/Configuration/**template**) (Required) Specify the name and path to your CloudFormation or AWS SAM template file. The template can be in JSON or YAML format, and can reside in a source repository, an artifact from a previous action, or an Amazon S3 bucket. If the template file is in a source repository or artifact, the path is relative to the source or artifact root. If the template is in an Amazon S3 bucket, the path is the template's **Object URL** value. Examples: `./MyFolder/MyTemplate.json` `MyFolder/MyTemplate.yml` `https://MyBucket.s3.us-west-2.amazonaws.com/MyTemplate.yml` **Note** You may need to add a prefix to the template's file path to indicate which artifact or source to find it in. For more information, see [Referencing source repository files](workflows-sources-reference-files.md) and [Referencing files in an artifact](workflows-working-artifacts-refer-files.md). Corresponding UI: Configuration tab/**Template** ## role-arn (*DeployCloudFormationStack*/Configuration/**role-arn**) (Required) Specify the Amazon Resource Name (ARN) of the stack role. CloudFormation uses this role to access and modify resources in your stack. For example: `arn:aws:iam::123456789012:role/StackRole`. Make sure the stack role includes: + One or more permissions policies. The policies depend on the resources you have in your stack. For example, if your stack includes an AWS Lambda function, you need to add permissions that grant access to Lambda. If you followed the tutorial described in [Tutorial: Deploy a serverless application](deploy-tut-lambda.md), it includes a procedure titled, [To create a stack role](deploy-tut-lambda.md#deploy-tut-lambda-cfn-roles-stack) that lists the permissions that the stack role needs if you're deploying a typical serverless application stack. **Warning** Limit the permissions to those required by the CloudFormation service to access resources in your stack. Using a role with broader permissions might pose a security risk. + The following trust policy: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "", "Effect": "Allow", "Principal": { "Service": "cloudformation.amazonaws.com" }, "Action": "sts:AssumeRole" } ] } ``` ------ Optionally, associate this role with your account connection. To learn more about associating an IAM role with an account connection, see [Adding IAM roles to account connections](ipa-connect-account-addroles.md). If you do not associate the stack role with the account connection, then the stack role will not appear in the **Stack role** drop-down list in the visual editor; however, the role ARN can still be specified in the `role-arn` field using the YAML editor. **Note** You can use the `CodeCatalystWorkflowDevelopmentRole-spaceName` role with this action, if you'd like. For more information about this role, see [Creating the **CodeCatalystWorkflowDevelopmentRole-*spaceName*** role for your account and space](ipa-iam-roles.md#ipa-iam-roles-service-create). Understand that the `CodeCatalystWorkflowDevelopmentRole-spaceName` role has full access permissions which may pose a security risk. We recommend that you only use this role in tutorials and scenarios where security is less of a concern. Corresponding UI: Configuration tab/**Stack role - optional** ## capabilities (*DeployCloudFormationStack*/Configuration/**capabilities**) (Required) Specify a list of IAM capabilities that are required to allow CloudFormation to create certain stacks. In most cases, you can leave `capabilities` with the default value of `CAPABILITY_IAM,CAPABILITY_NAMED_IAM,CAPABILITY_AUTO_EXPAND`. If you see `##[error] requires capabilities: [capability-name]` in your **Deploy CloudFormation stack** action's logs, see [How do I fix IAM capabilities errors?](troubleshooting-workflows.md#troubleshooting-workflows-capabilities) for information about how to fix the problem. For more information about IAM capabilities, see [Acknowledging IAM resources in CloudFormation templates](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-iam-template.html#using-iam-capabilities) in the *IAM User Guide*. Corresponding UI: Configuration tab/Advanced/**Capabilities** ## parameter-overrides (*DeployCloudFormationStack*/Configuration/**parameter-overrides**) (Optional) Specify parameters in your CloudFormation or AWS SAM template that don't have default values, or for which you want to specify non-default values. For more information about parameters, see [Parameters](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/parameters-section-structure.html) in the * AWS CloudFormation User Guide*. The `parameter-overrides` property accepts: + A JSON file containing the parameters and values. + A comma-separate list of parameters and values. **To specify a JSON file** 1. Make sure the JSON file uses one of the following syntaxes: ``` { "Parameters": { "Param1": "Value1", "Param2": "Value2", ... } } ``` Or... ``` [ { "ParameterKey": "Param1", "ParameterValue": "Value1" }, ... ] ``` (There are other syntaxes, but they are not supported by CodeCatalyst at the time of writing.) For more information about specifying CloudFormation parameters in a JSON file, see [Supported JSON syntax](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/cloudformation/deploy/index.html#supported-json-syntax) in the *AWS CLI Command Reference*. 1. Specify the path to the JSON file using one of the following formats: + If your JSON file resides in an output artifact from a previous action, use: `file:///artifacts/current-action-name/output-artifact-name/path-to-json-file` See **Example 1** for details. + If your JSON file resides in your source repository, use: `file:///sources/WorkflowSource/path-to-json-file` See **Example 2** for details. **Example 1** – The JSON file resides in an output artifact ``` ##My workflow YAML ... Actions: MyBuildAction: Identifier: aws/build@v1 Outputs: Artifacts: - Name: ParamArtifact Files: - params.json Configuration: ... MyDeployCFNStackAction: Identifier: aws/cfn-deploy@v1 Configuration: parameter-overrides: file:///artifacts/MyDeployCFNStackAction/ParamArtifact/params.json ``` **Example 2** – The JSON file resides in your source repository, in a folder called `my/folder` ``` ##My workflow YAML ... Actions: MyDeployCloudFormationStack: Identifier: aws/cfn-deploy@v1 Inputs: Sources: - WorkflowSource Configuration: parameter-overrides: file:///sources/WorkflowSource/my/folder/params.json ``` **To use a comma-separate list of parameters** + Add parameter name-value pairs in the `parameter-overrides` property using the following format: `param-1=value-1,param-2=value-2` For example, assuming the following CloudFormation template: ``` ##My CloudFormation template Description: My CloudFormation template Parameters: InstanceType: Description: Defines the Amazon EC2 compute for the production server. Type: String Default: t2.micro AllowedValues: - t2.micro - t2.small - t3.medium Resources: ... ``` ...you might set the `parameter-overrides` property as follows: ``` ##My workflow YAML ... Actions: ... DeployCloudFormationStack: Identifier: aws/cfn-deploy@v1 Configuration: parameter-overrides: InstanceType=t3.medium,UseVPC=true ``` **Note** You can specify a parameter name without a corresponding value using `undefined` as the value. For example: `parameter-overrides: MyParameter=undefined` The effect is that during a stack update, CloudFormation uses the existing parameter value for the given parameter name. Corresponding UI: + Configuration tab/Advanced/**Parameter overrides** + Configuration tab/Advanced/Parameter overrides/**Specify overrides using a file** + Configuration tab/Advanced/Parameter overrides/**Specify overrides using a value set** ## no-execute-changeset (*DeployCloudFormationStack*/Configuration/**no-execute-changeset**) (Optional) Specify whether you want CodeCatalyst to create the CloudFormation change set and then stop before running it. This gives you the opportunity to review the change set in the CloudFormation console. If you determine that the change set looks good, disable this option and then re-run the workflow so that CodeCatalyst can create and run the change set without stopping. The default is to create and run the change set without stopping. For more information, see the CloudFormation [deploy](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/deploy/index.html) parameter in the *AWS CLI Command Reference*. For more information about viewing change sets, see [Viewing a change set](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-changesets-view.html) in the *AWS CloudFormation User Guide*. Corresponding UI: Configuration tab/Advanced/**No execute change set** ## fail-on-empty-changeset (*DeployCloudFormationStack*/Configuration/**fail-on-empty-changeset**) (Optional) Specify whether you want CodeCatalyst to fail the **Deploy CloudFormation stack** action if the CloudFormation change set is empty. (If a change set is empty, it means there were no changes made to the stack during the latest deployment.) The default is to allow the action to proceed if the change set is empty, and to return an `UPDATE_COMPLETE` message even though the stack was not updated. For more information about this setting, see the CloudFormation [deploy](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/deploy/index.html) parameter in the *AWS CLI Command Reference*. For more information about change sets, see [Updating stacks using change sets](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-changesets.html) in the *AWS CloudFormation User Guide*. Corresponding UI: Configuration tab/Advanced/**Fail on empty changeset** ## disable-rollback (*DeployCloudFormationStack*/Configuration/**disable-rollback**) (Optional) Specify whether you want CodeCatalyst to roll back the stack deployment if it fails. The rollback returns the stack to the last known stable state. The default is to enable rollbacks. For more information about this setting, see the CloudFormation [deploy](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/deploy/index.html) parameter in the *AWS CLI Command Reference*. For more information about how the **Deploy CloudFormation stack** action handles rollbacks, see [Configuring rollbacks](deploy-consumption-enable-alarms.md). For more information about rolling back a stack, see [Stack failure options](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/stack-failure-options.html) in the *AWS CloudFormation User Guide*. Corresponding UI: Configuration tab/Advanced/**Disable rollback** ## termination-protection (*DeployCloudFormationStack*/Configuration/**termination-protection**) (Optional) Specify whether you want the **Deploy CloudFormation stack** to add termination protection to the stack that it is deploying. If a user attempts to delete a stack with termination protection enabled, the deletion fails and the stack, including its status, remains unchanged. The default is to disable termination protection. For more information, see [Protecting a stack from being deleted](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-protect-stacks.html) in the *AWS CloudFormation User Guide*. Corresponding UI: Configuration tab/Advanced/**Termination protection** ## timeout-in-minutes (*DeployCloudFormationStack*/Configuration/**timeout-in-minutes**) (Optional) Specify the amount of time, in minutes, that CloudFormation should allot before timing out stack creation operations and setting the stack status to `CREATE_FAILED`. If CloudFormation can't create the entire stack in the time allotted, it fails the stack creation due to timeout and rolls back the stack. By default, there is no timeout for stack creation. However, individual resources may have their own timeouts based on the nature of the service they implement. For example, if an individual resource in your stack times out, stack creation also times out even if the timeout you specified for stack creation hasn't yet been reached. Corresponding UI: Configuration tab/Advanced/**CloudFormation timeout** ## notification-arns (*DeployCloudFormationStack*/Configuration/**notification-arns**) (Optional) Specify the ARN of an Amazon SNS topic that you want CodeCatalyst to send notification messages to. For example, `arn:aws:sns:us-east-1:111222333:MyTopic`. When the **Deploy CloudFormation stack** action runs, CodeCatalyst coordinates with CloudFormation to send one notification per CloudFormation event that occurs during the stack creation or update process. (The events are visible in the CloudFormation console's **Events** tab for the stack.) You can specify up to five topics. For more information, see [What is Amazon SNS?](https://docs.aws.amazon.com/sns/latest/dg/welcome.html). Corresponding UI: Configuration tab/Advanced/**Notification ARNs** ## monitor-alarm-arns (*DeployCloudFormationStack*/Configuration/**monitor-alarm-arns**) (Optional) Specify the Amazon Resource Name (ARN) of an Amazon CloudWatch alarm to use as a rollback trigger. For example, `arn:aws:cloudwatch::123456789012:alarm/MyAlarm`. You can have a maximum of five rollback triggers. **Note** If you specify a CloudWatch alarm ARN, you'll also need to configure additional permissions to enable the action to access CloudWatch. For more information, see [Configuring rollbacks](deploy-consumption-enable-alarms.md). Corresponding UI: Configuration tab/Advanced/**Monitor alarm ARNs ** ## monitor-timeout-in-minutes (*DeployCloudFormationStack*/Configuration/**monitor-timeout-in-minutes**) (Optional) Specify an amount of time, from 0 to 180 minutes, during which CloudFormation monitors the specified alarms. Monitoring begins *after* all the stack resources have been deployed. If the alarm occurs within the specified monitoring time, then the deployment fails, and CloudFormation rolls back the entire stack operation. Default: 0. CloudFormation only monitors alarms while the stack resources are being deployed, not after. Corresponding UI: Configuration tab/Advanced/**Monitoring time** ## tags (*DeployCloudFormationStack*/Configuration/**tags**) (Optional) Specify tags to attach to your CloudFormation stack. Tags are arbitrary key-value pairs that you can use to identify your stack for purposes such as cost allocation. For more information about what tags are and how they can be used, see [Tagging your resources](https://docs.aws.amazon.com/) in the *Amazon EC2 User Guide*. For more information about tagging in CloudFormation, see [Setting CloudFormation stack options](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/cfn-console-add-tags.html) in the *AWS CloudFormation User Guide*. A key can have alphanumeric characters or spaces, and can have up to 127 characters. A value can have alphanumeric characters or spaces, and can have up to 255 characters. You can add up to 50 unique tags for each stack. Corresponding UI: Configuration tab/Advanced/**Tags**