What is the Amazon Serverless Application Model (Amazon SAM)? - Amazon Serverless Application Model
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

What is the Amazon Serverless Application Model (Amazon SAM)?

The Amazon Serverless Application Model (Amazon SAM) is a toolkit that improves the developer experience of building and running serverless applications on Amazon. Amazon SAM consists of two primary parts:

  1. Amazon SAM template specification – An open-source framework that you can use to define your serverless application infrastructure on Amazon.

  2. Amazon SAM command line interface (Amazon SAM CLI) – A command line tool that you can use with Amazon SAM templates and supported third-party integrations to build and run your serverless applications.

Are you new to serverless?

We recommend a basic understanding of the following topics:

To learn more, see Serverless concepts.

What is the Amazon SAM template specification?

The Amazon SAM template specification is an open-source framework that you can use to define and manage your serverless application infrastructure code. The Amazon SAM template specification is:

  • Built on Amazon CloudFormation – Use the Amazon CloudFormation syntax directly within your Amazon SAM template, taking advantage of its extensive support of resource and property configurations. If you are already familiar with Amazon CloudFormation, you don't have to learn a new service to manage your application infrastructure code.

  • An extension of Amazon CloudFormation – Amazon SAM offers its own unique syntax that focuses specifically on speeding up serverless development. You can use both the Amazon CloudFormation and Amazon SAM syntax within the same template.

  • An abstract, short-hand syntax – Using the Amazon SAM syntax, you can define your infrastructure quickly, in fewer lines of code, and with a lower chance of errors. Its syntax is especially curated to abstract away the complexity in defining your serverless application infrastructure.

  • Transformational – Amazon SAM does the complex work of transforming your template into the code necessary to provision your infrastructure through Amazon CloudFormation.

Here’s an example of a basic serverless application. This application processes requests to get all items from a database through an HTTP request. It consists of the following parts:

  1. A function that contains the logic to process the request.

  2. An HTTP API to serve as communication between the client (requestor) and the application.

  3. A database to store items.

  4. Permissions for the application to run securely.


				Application architecture of simple serverless application.

This application's infrastructure code can be defined in the following Amazon SAM template:

AWSTemplateFormatVersion: 2010-09-09 Transform: AWS::Serverless-2016-10-31 Resources: getAllItemsFunction: Type: AWS::Serverless::Function Properties: Handler: src/get-all-items.getAllItemsHandler Runtime: nodejs12.x Events: Api: Type: HttpApi Properties: Path: / Method: GET Connectors: MyConn: Properties: Destination: Id: SampleTable Permissions: - Read SampleTable: Type: AWS::Serverless::SimpleTable

In 23 lines of code, the following infrastructure is defined:

  • A function using the Amazon Lambda service.

  • An HTTP API using the Amazon API Gateway service.

  • A database using the Amazon DynamoDB service.

  • The Amazon Identity and Access Management (IAM) permissions necessary for these services to interact with one another.

To provision this infrastructure, the template is deployed to Amazon CloudFormation. During deployment, Amazon SAM transforms the 23 lines of code into the Amazon CloudFormation syntax required to generate these resources in Amazon. The transformed Amazon CloudFormation template contains over 200 lines of code!

{ "AWSTemplateFormatVersion": "2010-09-09", "Resources": { "getAllItemsFunction": { "Type": "AWS::Lambda::Function", "Metadata": { "SamResourceId": "getAllItemsFunction" }, "Properties": { "Code": { "S3Bucket": "aws-sam-cli-managed-default-samclisourcebucket-1a4x26zbcdkqr", "S3Key": "what-is-app/a6f856abf1b2c4f7488c09b367540b5b" }, "Handler": "src/get-all-items.getAllItemsHandler", "Role": { "Fn::GetAtt": [ "getAllItemsFunctionRole", "Arn" ] }, "Runtime": "nodejs12.x", "Tags": [ { "Key": "lambda:createdBy", "Value": "SAM" } ] } }, "getAllItemsFunctionRole": { "Type": "AWS::IAM::Role", "Properties": { "AssumeRolePolicyDocument": { "Version": "2012-10-17", "Statement": [ { "Action": [ "sts:AssumeRole" ], "Effect": "Allow", "Principal": { "Service": [ "lambda.amazonaws.com" ] } } ] }, "ManagedPolicyArns": [ "arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole" ], "Tags": [ { "Key": "lambda:createdBy", "Value": "SAM" } ] } }, "getAllItemsFunctionApiPermission": { "Type": "AWS::Lambda::Permission", "Properties": { "Action": "lambda:InvokeFunction", "FunctionName": { "Ref": "getAllItemsFunction" }, "Principal": "apigateway.amazonaws.com", "SourceArn": { "Fn::Sub": [ "arn:${AWS::Partition}:execute-api:${AWS::Region}:${AWS::AccountId}:${__ApiId__}/${__Stage__}/GET/", { "__ApiId__": { "Ref": "ServerlessHttpApi" }, "__Stage__": "*" } ] } } }, "ServerlessHttpApi": { "Type": "AWS::ApiGatewayV2::Api", "Properties": { "Body": { "info": { "version": "1.0", "title": { "Ref": "AWS::StackName" } }, "paths": { "/": { "get": { "x-amazon-apigateway-integration": { "httpMethod": "POST", "type": "aws_proxy", "uri": { "Fn::Sub": "arn:${AWS::Partition}:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${getAllItemsFunction.Arn}/invocations" }, "payloadFormatVersion": "2.0" }, "responses": {} } } }, "openapi": "3.0.1", "tags": [ { "name": "httpapi:createdBy", "x-amazon-apigateway-tag-value": "SAM" } ] } } }, "ServerlessHttpApiApiGatewayDefaultStage": { "Type": "AWS::ApiGatewayV2::Stage", "Properties": { "ApiId": { "Ref": "ServerlessHttpApi" }, "StageName": "$default", "Tags": { "httpapi:createdBy": "SAM" }, "AutoDeploy": true } }, "SampleTable": { "Type": "AWS::DynamoDB::Table", "Metadata": { "SamResourceId": "SampleTable" }, "Properties": { "AttributeDefinitions": [ { "AttributeName": "id", "AttributeType": "S" } ], "KeySchema": [ { "AttributeName": "id", "KeyType": "HASH" } ], "BillingMode": "PAY_PER_REQUEST" } }, "getAllItemsFunctionMyConnPolicy": { "Type": "AWS::IAM::ManagedPolicy", "Metadata": { "aws:sam:connectors": { "getAllItemsFunctionMyConn": { "Source": { "Type": "AWS::Serverless::Function" }, "Destination": { "Type": "AWS::Serverless::SimpleTable" } } } }, "Properties": { "PolicyDocument": { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "dynamodb:GetItem", "dynamodb:Query", "dynamodb:Scan", "dynamodb:BatchGetItem", "dynamodb:ConditionCheckItem", "dynamodb:PartiQLSelect" ], "Resource": [ { "Fn::GetAtt": [ "SampleTable", "Arn" ] }, { "Fn::Sub": [ "${DestinationArn}/index/*", { "DestinationArn": { "Fn::GetAtt": [ "SampleTable", "Arn" ] } } ] } ] } ] }, "Roles": [ { "Ref": "getAllItemsFunctionRole" } ] } } } }

By using Amazon SAM, you define 23 lines of infrastructure code. Amazon SAM transforms your code into the 200+ lines of Amazon CloudFormation code necessary to provision your application.

What is the Amazon SAM CLI?

The Amazon SAM CLI is a command line tool that you can use with Amazon SAM templates and supported third-party integrations to build and run your serverless applications. Use the Amazon SAM CLI to:

  • Quickly initialize a new application project.

  • Build your application for deployment.

  • Perform local debugging and testing.

  • Deploy your application.

  • Configure CI/CD deployment pipelines.

  • Monitor and troubleshoot your application in the cloud.

  • Sync local changes to the cloud as you develop.

  • And more!

The Amazon SAM CLI is best utilized when used with Amazon SAM and Amazon CloudFormation templates. It also works with third-party products such as Terraform.

Initialize a new project

Select from starter templates or choose a custom template location to begin a new project.

Here, we use the sam init command to initialize a new application project. We select the Hello World Example project to start with. The Amazon SAM CLI downloads a starter template and creates our project folder directory structure.


					Using sam init to start a new application project with the
						Amazon SAM CLI.

Build your application for deployment

Package your function dependencies and organize your project code and folder structure to prepare for deployment.

Here, we use the sam build command to prepare our application for deployment. The Amazon SAM CLI creates a .aws-samdirectory and organizes our application dependencies and files there for deployment.


					Using sam build to prepare an application for
						deployment.

Perform local debugging and testing

On your local machine, simulate events, test APIs, invoke functions, and more to debug and test your application.

Here, we use the sam local invoke command to invoke our HelloWorldFunction locally. To accomplish this, the Amazon SAM CLI creates a local container, builds our function, invokes it, and outputs the results.


					Using the Amazon SAM CLI sam local invoke command to locally invoke
						a function.

Deploy your application

Configure your application's deployment settings and deploy to the Amazon Cloud to provision your resources.

Here, we use the sam deploy --guided command to deploy our application through an interactive flow. The Amazon SAM CLI guides us through configuring our application's deployment settings, transforms our template into Amazon CloudFormation, and deploys to Amazon CloudFormation to create our resources.


					Using the Amazon SAM CLI sam deploy command to deploy an application
						to the Amazon Cloud.

Configure CI/CD deployment pipelines

Create secure continuous integration and delivery (CI/CD) pipelines, using a supported CI/CD system.

Here, we use the sam pipeline init --bootstrap command to configure a CI/CD deployment pipeline for our application. The Amazon SAM CLI guides us through our options and generates the Amazon resources and configuration file to use with our CI/CD system.


					Using the Amazon SAM CLI sam pipeline init --bootstrap command to
						configure a CI/CD pipeline with our preferred CI/CD system.

Monitor and troubleshoot your application in the cloud

View important information about your deployed resources, gather logs, and utilize built-in monitoring tools such as Amazon X-Ray.

Here, we use the sam list command to view our deployed resources. We get our API endpoint and invoke it, which triggers our function. Then, we use sam logs to view our function's logs.


					Using the Amazon SAM CLI sam list command to obtain our API
						endpoint. Then, sam logs is used to view our function's
						logs.

Sync local changes to the cloud as you develop

As you develop on your local machine, automatically sync changes to the cloud. Quickly see your changes and perform testing and validation in the cloud.

Here, we use the sam sync --watch command to have the Amazon SAM CLI watch for local changes. We modify our HelloWorldFunction code and the Amazon SAM CLI automatically detects the change and deploys our updates to the cloud.


					Using the Amazon SAM CLI sam sync command to sync local changes to
						the Amazon Cloud.

Test supported resources in the cloud

Invoke and pass events to supported resources in the cloud.

Here, we use the sam remote invoke command to test a deployed Lambda function in the cloud. We invoke our Lambda function and receive its logs and response. With our Lambda function configured to stream responses, the Amazon SAM CLI streams its response back in real time.


					Using the Amazon SAM CLI sam remote invoke command to test our
						deployed function in the Amazon Cloud.

Benefits of using Amazon SAM

Here are some examples of what you can accomplish with Amazon SAM:

Define your application infrastructure code quickly, using less code

Author Amazon SAM templates to define your serverless application infrastructure code. Deploy your templates directly to Amazon CloudFormation to provision your resources.

Manage your serverless applications through their entire development lifecycle

Use the Amazon SAM CLI to manage your serverless application through the authoring, building, deploying, testing, and monitoring phases of your development lifecycle. For more information, see Using the Amazon SAM CLI.

Quickly provision permissions between resources with Amazon SAM connectors

Use Amazon SAM connectors in your Amazon SAM templates to define permissions between your Amazon resources. Amazon SAM transforms your code into the IAM permissions required to facilitate your intent. For more information, see Managing resource permissions with Amazon SAM connectors.

Continuously sync local changes to the cloud as you develop

Use the Amazon SAM CLI sam sync command to automatically sync local changes to the cloud, speeding up your development and cloud testing workflows. For more information, see Using sam sync.

Manage your Terraform serverless applications

Use the Amazon SAM CLI to perform local debugging and testing of your Lambda functions and layers. For more information, see Amazon SAM CLI Terraform support.

Learn more

To continue learning about Amazon SAM, see the following resources:

  • The Complete Amazon SAM Workshop – A workshop designed to teach you many of the major features that Amazon SAM provides.

  • Sessions with SAM – Video series created by our Amazon Serverless Developer Advocate team on using Amazon SAM.

  • Serverless Land – Site that brings together the latest information, blogs, videos, code, and learning resources for Amazon serverless.

Next steps

If this is your first time using Amazon SAM, see Getting started with Amazon SAM.