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 offers a variety of benefits:

Basic Concepts

Amazon SAM consists of three primary parts:

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:

What is the Amazon SAM template?

An Amazon SAM template is what you use to access Amazon SAM template specifications, the open-source framework that you can use to define your serverless application infrastructure on Amazon, with some additional components that make them easier to work with. In this sense, Amazon SAM templates are an extension of Amazon CloudFormation templates.

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:

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:

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:

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.

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.

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.

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.

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.

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.

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.

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.

Learn more

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

Next steps

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