Using Application Composer with AWS CloudFormation and AWS SAM
Use AWS Application Composer to design deployment-ready serverless applications. To deploy, use any AWS CloudFormation compatible service. We recommend using the AWS Serverless Application Model (AWS SAM).
What is AWS SAM?
AWS SAM is an open-source framework that provides developer tools for building and running serverless applications on AWS. The AWS SAM toolkit consists of two primary parts:
-
AWS SAM template specification
-
AWS SAM Command Line Interface (AWS SAM CLI)
AWS SAM template specification
The AWS SAM template specification contains a short-hand syntax and structure that you can use to define the infrastructure of your AWS serverless applications.
-
AWS SAM templates can be defined in JSON and YAML.
-
Its syntax is short-hand, making it quicker to learn and code. Less code means fewer errors and faster development.
AWS SAM templates are an extension of AWS CloudFormation, which is a service that provisions resources at AWS.
-
AWS SAM templates are automatically transformed into the AWS CloudFormation template syntax at deployment.
-
You can deploy AWS SAM templates directly to AWS CloudFormation to create your application resources.
When you design your application in Application Composer, AWS SAM templates are automatically created for you. You can select the Template view to view and modify your AWS SAM template.
AWS SAM CLI
The AWS SAM CLI is a command line tool that helps you manage your serverless applications through their entire development lifecycle. You can use the AWS SAM CLI to:
-
Prepare your application for deployment.
-
Perform local debugging and testing.
-
Deploy your application.
-
Develop and sync local changes to the cloud.
-
And more!
The AWS SAM CLI is a great companion to Application Composer. Use Application Composer to design deployment-ready applications. Then use the AWS SAM CLI to deploy and manage your applications.
To learn more about AWS SAM, see What is AWS SAM? in the AWS Serverless Application Model Developer Guide.
AWS SAM prerequisites
Install the AWS CLI
We recommend installing and setting up the AWS CLI before installing the AWS SAM CLI. For instructions, see AWS SAM prerequisites in the AWS Serverless Application Model Developer Guide.
Note
After installing the AWS CLI, you must configure AWS credentials. To learn more, see Quick setup in the AWS Command Line Interface User Guide.
Install the AWS SAM CLI
To install the AWS SAM CLI, see Installing the AWS SAM CLI in the AWS Serverless Application Model Developer Guide.
Using Application Composer with the AWS SAM CLI
Application Composer from the console
If you use Application Composer from the AWS Management Console, you have the following options to use the AWS SAM CLI.
- Activate local sync mode
-
With local sync mode, your project folder, including the AWS SAM template, are automatically saved to your local machine. Application Composer structures your project directory in a way that AWS SAM recognizes. You can run the AWS SAM CLI from the root directory of your project.
For more information about local sync mode, see Local sync mode.
- Export your template
-
You can export your template to your local machine. Then, run the AWS SAM CLI from the parent folder that contains the template. You can also use the
--template-fileoption with any AWS SAM CLI command and provide the path to your template. - Use Application Composer from the AWS Toolkit for Visual Studio Code
-
You can use Application Composer from the Toolkit for VS Code to bring Application Composer to your local machine. Then, use Application Composer and the AWS SAM CLI from VS Code.
Build your application
Building your application involves taking your AWS SAM template, AWS Lambda function code, and any language-specific files and dependencies, and placing these build artifacts in the proper structure and location for deployment. You can use the sam build command to build your application.
To learn more about building applications with AWS SAM, see the following from the AWS Serverless Application Model Developer Guide:
Deploy your application
Deploy your application to AWS CloudFormation to provision the resources and infrastructure defined in your AWS SAM templates. You can use the sam deploy command to deploy your application.
-
You can deploy to create new resources or update existing resources.
-
The AWS SAM CLI saves your deployment preferences in a configuration file.
-
A deployed application in AWS CloudFormation is called a stack. To learn more, see Working with stacks in the AWS CloudFormation User Guide.
To learn more about deploying applications with AWS SAM, see the following from the AWS Serverless Application Model Developer Guide:
Test your application locally
Use the AWS SAM CLI to test your application locally. You can simulate events, start up APIs, invoke functions, and more.
Local testing requires Docker on your local machine. For more information, see Installing Docker to use with the AWS SAM CLI in the AWS Serverless Application Model Developer Guide.
To learn more about testing locally, see the following from the AWS Serverless Application Model Developer Guide:
Sync local changes to the cloud
As you design your application in Application Composer, you can use the sam sync command to have the AWS SAM CLI automatically detect local changes and deploy those changes to AWS CloudFormation.
To learn more, see the following from the AWS Serverless Application Model Developer Guide:
Examples
Build and deploy a serverless application
In this example, we build and deploy the Application Composer demo application.
-
To learn more about the demo application, see Tutorial 1: Load and modify the Application Composer demo project.
-
For this example, we will be using Application Composer with local sync activated.
Use the sam build command to build the application.
$sam build... Build Succeeded Built Artifacts : .aws-sam/build Built Template : .aws-sam/build/template.yaml Commands you can use next ========================= [*] Validate SAM template: sam validate [*] Invoke Function: sam local invoke [*] Test Function in the Cloud: sam sync --stack-name {{stack-name}} --watch [*] Deploy: sam deploy --guided
The AWS SAM CLI creates the ./aws-sam directory in the project folder. This directory
contains build artifacts for the application’s Lambda functions. Here is an output of the project
directory:
. ├── README.md ├── samconfig.toml ├── src │ ├── CreateItem │ │ ├── index.js │ │ └── package.json │ ├── DeleteItem │ │ ├── index.js │ │ └── package.json │ ├── GetItem │ │ ├── index.js │ │ └── package.json │ ├── ListItems │ │ ├── index.js │ │ └── package.json │ └── UpdateItem │ ├── index.js │ └── package.json └── template.yaml
Now, the application is ready to be deployed. We will use sam deploy --guided. This prepares your application for deployment through a series of prompts.
$sam deploy --guided... Configuring SAM deploy ====================== Looking for config file [samconfig.toml] : Found Reading default arguments : Success Setting default arguments for 'sam deploy' ========================================= Stack Name [aws-app-composer-basic-api]: AWS Region [us-west-2]: #Shows you resources changes to be deployed and require a 'Y' to initiate deploy Confirm changes before deploy [y/N]: #SAM needs permission to be able to create roles to connect to the resources in your template Allow SAM CLI IAM role creation [Y/n]: #Preserves the state of previously provisioned resources when an operation fails Disable rollback [y/N]: ListItems may not have authorization defined, Is this okay? [y/N]:yCreateItem may not have authorization defined, Is this okay? [y/N]:yGetItem may not have authorization defined, Is this okay? [y/N]:yUpdateItem may not have authorization defined, Is this okay? [y/N]:yDeleteItem may not have authorization defined, Is this okay? [y/N]:ySave arguments to configuration file [Y/n]: SAM configuration file [samconfig.toml]: SAM configuration environment [default]:
The AWS SAM CLI displays a summary of what will be deployed:
Deploying with following values
===============================
Stack name : aws-app-composer-basic-api
Region : us-west-2
Confirm changeset : False
Disable rollback : False
Deployment s3 bucket : aws-sam-cli-managed-default-samclisourcebucket-1b3x26zbcdkqr
Capabilities : ["CAPABILITY_IAM"]
Parameter overrides : {}
Signing Profiles : {}
The AWS SAM CLI deploys the application, first by creating an AWS CloudFormation changeset:
Initiating deployment
=====================
Uploading to aws-app-composer-basic-api/4181c909ee2440a728a7a129dafb83d4.template 7087 / 7087 (100.00%)
Waiting for changeset to be created..
CloudFormation stack changeset
---------------------------------------------------------------------------------------------------------------------------------------------
Operation LogicalResourceId ResourceType Replacement
---------------------------------------------------------------------------------------------------------------------------------------------
+ Add ApiDeploymentcc153d135b AWS::ApiGateway::Deployment N/A
+ Add ApiProdStage AWS::ApiGateway::Stage N/A
+ Add Api AWS::ApiGateway::RestApi N/A
+ Add CreateItemApiPOSTitemsPermissionP AWS::Lambda::Permission N/A
rod
+ Add CreateItemRole AWS::IAM::Role N/A
+ Add CreateItem AWS::Lambda::Function N/A
+ Add DeleteItemApiDELETEitemsidPermiss AWS::Lambda::Permission N/A
ionProd
+ Add DeleteItemRole AWS::IAM::Role N/A
+ Add DeleteItem AWS::Lambda::Function N/A
+ Add GetItemApiGETitemsidPermissionPro AWS::Lambda::Permission N/A
d
+ Add GetItemRole AWS::IAM::Role N/A
+ Add GetItem AWS::Lambda::Function N/A
+ Add Items AWS::DynamoDB::Table N/A
+ Add ListItemsApiGETitemsPermissionPro AWS::Lambda::Permission N/A
d
+ Add ListItemsRole AWS::IAM::Role N/A
+ Add ListItems AWS::Lambda::Function N/A
+ Add UpdateItemApiPUTitemsidPermission AWS::Lambda::Permission N/A
Prod
+ Add UpdateItemRole AWS::IAM::Role N/A
+ Add UpdateItem AWS::Lambda::Function N/A
---------------------------------------------------------------------------------------------------------------------------------------------
Changeset created successfully. arn:aws:cloudformation:us-west-2:513423067560:changeSet/samcli-deploy1677472539/967ab543-f916-4170-b97d-c11a6f9308ea
Then, the AWS SAM CLI deploys the application:
CloudFormation events from stack operations (refresh every 0.5 seconds)
---------------------------------------------------------------------------------------------------------------------------------------------
ResourceStatus ResourceType LogicalResourceId ResourceStatusReason
---------------------------------------------------------------------------------------------------------------------------------------------
CREATE_IN_PROGRESS AWS::DynamoDB::Table Items -
CREATE_IN_PROGRESS AWS::DynamoDB::Table Items Resource creation Initiated
CREATE_COMPLETE AWS::DynamoDB::Table Items -
CREATE_IN_PROGRESS AWS::IAM::Role DeleteItemRole -
CREATE_IN_PROGRESS AWS::IAM::Role ListItemsRole -
CREATE_IN_PROGRESS AWS::IAM::Role UpdateItemRole -
CREATE_IN_PROGRESS AWS::IAM::Role GetItemRole -
CREATE_IN_PROGRESS AWS::IAM::Role CreateItemRole -
CREATE_IN_PROGRESS AWS::IAM::Role DeleteItemRole Resource creation Initiated
CREATE_IN_PROGRESS AWS::IAM::Role ListItemsRole Resource creation Initiated
CREATE_IN_PROGRESS AWS::IAM::Role GetItemRole Resource creation Initiated
CREATE_IN_PROGRESS AWS::IAM::Role UpdateItemRole Resource creation Initiated
CREATE_IN_PROGRESS AWS::IAM::Role CreateItemRole Resource creation Initiated
CREATE_COMPLETE AWS::IAM::Role DeleteItemRole -
CREATE_COMPLETE AWS::IAM::Role ListItemsRole -
CREATE_COMPLETE AWS::IAM::Role GetItemRole -
CREATE_COMPLETE AWS::IAM::Role UpdateItemRole -
CREATE_COMPLETE AWS::IAM::Role CreateItemRole -
CREATE_IN_PROGRESS AWS::Lambda::Function DeleteItem -
CREATE_IN_PROGRESS AWS::Lambda::Function CreateItem -
CREATE_IN_PROGRESS AWS::Lambda::Function ListItems -
CREATE_IN_PROGRESS AWS::Lambda::Function UpdateItem -
CREATE_IN_PROGRESS AWS::Lambda::Function DeleteItem Resource creation Initiated
CREATE_IN_PROGRESS AWS::Lambda::Function GetItem -
CREATE_IN_PROGRESS AWS::Lambda::Function ListItems Resource creation Initiated
CREATE_IN_PROGRESS AWS::Lambda::Function CreateItem Resource creation Initiated
CREATE_IN_PROGRESS AWS::Lambda::Function UpdateItem Resource creation Initiated
CREATE_IN_PROGRESS AWS::Lambda::Function GetItem Resource creation Initiated
CREATE_COMPLETE AWS::Lambda::Function DeleteItem -
CREATE_COMPLETE AWS::Lambda::Function ListItems -
CREATE_COMPLETE AWS::Lambda::Function CreateItem -
CREATE_COMPLETE AWS::Lambda::Function UpdateItem -
CREATE_COMPLETE AWS::Lambda::Function GetItem -
CREATE_IN_PROGRESS AWS::ApiGateway::RestApi Api -
CREATE_IN_PROGRESS AWS::ApiGateway::RestApi Api Resource creation Initiated
CREATE_COMPLETE AWS::ApiGateway::RestApi Api -
CREATE_IN_PROGRESS AWS::Lambda::Permission GetItemApiGETitemsidPermissionPro -
d
CREATE_IN_PROGRESS AWS::Lambda::Permission ListItemsApiGETitemsPermissionPro -
d
CREATE_IN_PROGRESS AWS::Lambda::Permission DeleteItemApiDELETEitemsidPermiss -
ionProd
CREATE_IN_PROGRESS AWS::ApiGateway::Deployment ApiDeploymentcc153d135b -
CREATE_IN_PROGRESS AWS::Lambda::Permission UpdateItemApiPUTitemsidPermission -
Prod
CREATE_IN_PROGRESS AWS::Lambda::Permission CreateItemApiPOSTitemsPermissionP -
rod
CREATE_IN_PROGRESS AWS::Lambda::Permission GetItemApiGETitemsidPermissionPro Resource creation Initiated
d
CREATE_IN_PROGRESS AWS::Lambda::Permission UpdateItemApiPUTitemsidPermission Resource creation Initiated
Prod
CREATE_IN_PROGRESS AWS::Lambda::Permission CreateItemApiPOSTitemsPermissionP Resource creation Initiated
rod
CREATE_IN_PROGRESS AWS::Lambda::Permission ListItemsApiGETitemsPermissionPro Resource creation Initiated
d
CREATE_IN_PROGRESS AWS::Lambda::Permission DeleteItemApiDELETEitemsidPermiss Resource creation Initiated
ionProd
CREATE_IN_PROGRESS AWS::ApiGateway::Deployment ApiDeploymentcc153d135b Resource creation Initiated
CREATE_COMPLETE AWS::ApiGateway::Deployment ApiDeploymentcc153d135b -
CREATE_IN_PROGRESS AWS::ApiGateway::Stage ApiProdStage -
CREATE_IN_PROGRESS AWS::ApiGateway::Stage ApiProdStage Resource creation Initiated
CREATE_COMPLETE AWS::ApiGateway::Stage ApiProdStage -
CREATE_COMPLETE AWS::Lambda::Permission CreateItemApiPOSTitemsPermissionP -
rod
CREATE_COMPLETE AWS::Lambda::Permission UpdateItemApiPUTitemsidPermission -
Prod
CREATE_COMPLETE AWS::Lambda::Permission ListItemsApiGETitemsPermissionPro -
d
CREATE_COMPLETE AWS::Lambda::Permission DeleteItemApiDELETEitemsidPermiss -
ionProd
CREATE_COMPLETE AWS::Lambda::Permission GetItemApiGETitemsidPermissionPro -
d
CREATE_COMPLETE AWS::CloudFormation::Stack aws-app-composer-basic-api -
---------------------------------------------------------------------------------------------------------------------------------------------
Finally, a message is displayed, informing you that deployment was successful:
Successfully created/updated stack - aws-app-composer-basic-api in us-west-2
Delete an AWS CloudFormation stack
To delete an AWS CloudFormation stack, use the sam delete command:
$sam deleteAre you sure you want to delete the stack aws-app-composer-basic-api in the region us-west-2 ? [y/N]:yDo you want to delete the template file 30439348c0be6e1b85043b7a935b34ab.template in S3? [y/N]:y- Deleting S3 object with key eb226ca86d1bc4e9914ad85eb485fed8 - Deleting S3 object with key 875e4bcf4b10a6a1144ad83158d84b6d - Deleting S3 object with key 20b869d98d61746dedd9aa33aa08a6fb - Deleting S3 object with key c513cedc4db6bc184ce30e94602741d6 - Deleting S3 object with key c7a15d7d8d1c24b77a1eddf8caebc665 - Deleting S3 object with key e8b8984f881c3732bfb34257cdd58f1e - Deleting S3 object with key 3185c59b550594ee7fca7f8c36686119.template - Deleting S3 object with key 30439348c0be6e1b85043b7a935b34ab.template - Deleting Cloudformation stack aws-app-composer-basic-api Deleted successfully
