Menu
AWS Lambda
Developer Guide

Using the AWS Serverless Application Model (AWS SAM)

The AWS Serverless Application Model (AWS SAM) is a model to define serverless applications. AWS SAM is natively supported by AWS CloudFormation and defines simplified syntax for expressing serverless resources. The specification currently covers APIs, Lambda functions and Amazon DynamoDB tables. The specification is available under Apache 2.0 for AWS partners and customers to adopt and extend within their own toolsets. For details on the specification, see the AWS Serverless Application Model.

Serverless Resources Within AWS SAM

An AWS CloudFormation template with serverless resources conforming to the AWS SAM model is referred to as a SAM file or template.

The examples following illustrate how to leverage AWS SAM to declare common components of a serverless application. Note that the Handler and Runtime parameter values should match the ones you used when you created the function in the previous section.

Lambda function

The following shows the notation you use to describe a Lambda function:

Copy
AWSTemplateFormatVersion: '2010-09-09' Transform: AWS::Serverless-2016-10-31 Resources: FunctionName: Type: AWS::Serverless::Function Properties: Handler: index.handler Runtime: runtime CodeUri: s3://bucketName/codepackage.zip

The handler value of the Handler property points to the module containing the code your Lambda function will execute when invoked. The index value of the Handler property indicates the name of the file containing the code. You can declare as many functions as your serverless application requires.

You can also declare environment variables, which are configuration settings you can set for your application. The following shows an example of a serverless app with two Lambda functions and an environment variable that points to a DynamoDB table. You can update environment variables without needing to modify, repackage, or redeploy your Lambda function code. For more information, see Environment Variables.

Copy
AWSTemplateFormatVersion: '2010-09-09' Transform: AWS::Serverless-2016-10-31 Resources: PutFunction: Type: AWS::Serverless::Function Properties: Handler: index.handler Runtime: nodejs6.10 Policies: AWSLambdaDynamoDBExecutionRole CodeUri: s3://bucketName/codepackage.zip Environment: Variables: TABLE_NAME: !Ref Table DeleteFunction: Type: AWS::Serverless::Function Properties: Handler: index.handler Runtime: nodejs6.10 Policies: AWSLambdaDynamoDBExecutionRole CodeUri: s3://bucketName/codepackage.zip Environment: Variables: TABLE_NAME: !Ref Table Events: Stream: Type: DynamoDB Properties: Stream: !GetAtt DynamoDBTable.StreamArn BatchSize: 100 StartingPosition: TRIM_HORIZON DynamoDBTable: Type: AWS::DynamoDB::Table Properties: AttributeDefinitions: - AttributeName: id AttributeType: S KeySchema: - AttributeName: id KeyType: HASH ProvisionedThroughput: ReadCapacityUnits: 5 WriteCapacityUnits: 5 StreamSpecification: StreamViewType: streamview type

Note the notation at the top:

Copy
AWSTemplateFormatVersion: '2010-09-09' Transform: AWS::Serverless-2016-10-31

This is required in order to include objects defined by the AWS Serverless Application Model within an AWS CloudFormation template.

SimpleTable

SimpleTable is a resource that creates a DynamoDB table with a single-attribute primary key. You can use this simplified version if the data your serverless application is interacting with only needs to be accessed by a single-valued key. You could update the previous example to use a SimpleTable, as shown following:

Copy
AWSTemplateFormatVersion: '2010-09-09' Transform: AWS::Serverless-2016-10-31 Resources: TableName: Type: AWS::Serverless::SimpleTable Properties: PrimaryKey: Name: id Type: String ProvisionedThroughput: ReadCapacityUnits: 5 WriteCapacityUnits: 5

Events

Events are AWS resources that trigger the Lambda function, such as an Amazon API Gateway endpoint or an Amazon SNS notification. The Events property is an array, which allows you to set multiple events per function. The following shows the notation you use to describe a Lambda function with a DynamoDB table as an event source:

Copy
AWSTemplateFormatVersion: '2010-09-09' Transform: AWS::Serverless-2016-10-31 Resources: FunctionName: Type: AWS::Serverless::Function Properties: Handler: index.handler Runtime: nodejs6.10 Events: Stream: Type: DynamoDB Properties: Stream: !GetAtt DynamoDBTable.StreamArn BatchSize: 100 StartingPosition: TRIM_HORIZON TableName: Type: AWS::DynamoDB::Table Properties: AttributeDefinitions: - AttributeName: id AttributeType: S KeySchema: - AttributeName: id KeyType: HASH ProvisionedThroughput: ReadCapacityUnits: 5 WriteCapacityUnits: 5

As mentioned preceding, you can set multiple event sources that will trigger the Lambda function. The example following shows a Lambda function that can be triggered by either an HTTP PUT or POST event.

API

There are two ways to define an API using AWS SAM. The following uses Swagger to configure the underlying Amazon API Gateway resources:

Copy
AWSTemplateFormatVersion: '2010-09-09' Transform: AWS::Serverless-2016-10-31 Resources: Api: Type: AWS::Serverless::Api Properties: StageName: prod DefinitionUri: swagger.yml

In the next example, the AWS::Serverless::Api resource type is implicity added from the union of API events defined on AWS::Serverless::Function resources.

Copy
AWSTemplateFormatVersion: '2010-09-09' Transform: AWS::Serverless-2016-10-31 Resources: GetFunction: Type: AWS::Serverless::Function Properties: Handler: index.get Runtime: nodejs6.10 CodeUri: s3://bucket/api_backend.zip Policies: AmazonDynamoDBReadOnlyAccess Environment: Variables: TABLE_NAME: !Ref Table Events: GetResource: Type: Api Properties: Path: /resource/{resourceId} Method: get PutFunction: Type: AWS::Serverless::Function Properties: Handler: index.put Runtime: nodejs6.10 CodeUri: s3://bucket/api_backend.zip Policies: AmazonDynamoDBFullAccess Environment: Variables: TABLE_NAME: !Ref Table Events: PutResource: Type: Api Properties: Path: /resource/{resourceId} Method: put DeleteFunction: Type: AWS::Serverless::Function Properties: Handler: index.delete Runtime: nodejs6.10 CodeUri: s3://bucket/api_backend.zip Policies: AmazonDynamoDBFullAccess Environment: Variables: TABLE_NAME: !Ref Table Events: DeleteResource: Type: Api Properties: Path: /resource/{resourceId} Method: delete Table: Type: AWS::Serverless::SimpleTable

In the example preceding, AWS CloudFormation will automatically generate an Amazon API Gateway API with the path "/resource/{resourceId}" and with the methods GET, PUT and DELETE.

Permissions

You can supply an Amazon Resource Name (ARN) for an AWS Identity and Access Management (IAM) role be used as this function's execution role, as shown following:

Copy
AWSTemplateFormatVersion: '2010-09-09' Transform: AWS::Serverless-2016-10-31 Resources: FunctionName: Type: AWS::Serverless::Function Properties: Role:role arn

Alternatively, you could supply one or more managed policies to the Lambda function resource. AWS CloudFormation will then create a new role with the managed policies plus the default Lambda basic execution policy.

Copy
AWSTemplateFormatVersion: '2010-09-09' Transform: AWS::Serverless-2016-10-31 Resources: FunctionName: Type: AWS::Serverless::Function Properties: Policies: AmazonDynamoDBFullAccess

If none of these are supplied, a default execution role is created with Lambda basic execution permissions.

Note

In addition to using the serverless resources, you can also use conventional AWS CloudFormation syntax for expressing resources in the same template. Any resources not included in the current SAM model can still be created in the AWS CloudFormation template using AWS CloudFormation syntax. In addition, you can use AWS CloudFormation syntax to express serverless resources as an alternative to using the SAM model. For information about specifying a Lambda function using conventional CloudFormation syntax as part of your SAM template, see AWS::Lambda::Function in the AWS CloudFormation User Guide.

For a list of complete serverless application examples, see Examples of How to Use AWS Lambda.

Next Step

Create Your Own Serverless Application