AWS Serverless Application Model (SAM)
Version 2016-10-31
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
The AWS Serverless Application Model (SAM) is licensed under The Apache License, Version 2.0.
Introduction
AWS SAM is a model used to define serverless applications on AWS.
Serverless applications are applications composed of functions triggered by events. A typical serverless application consists of one or more AWS Lambda functions triggered by events such as object uploads to Amazon S3, Amazon SNS notifications, and API actions. Those functions can stand alone or leverage other resources such as Amazon DynamoDB tables or S3 buckets. The most basic serverless application is simply a function.
AWS SAM is based on AWS CloudFormation. A serverless application is defined in a CloudFormation template and deployed as a CloudFormation stack. An AWS SAM template is a CloudFormation template.
AWS SAM defines a set of objects which can be included in a CloudFormation template to describe common components of serverless applications easily.
Specification
Format
The files describing a serverless application in accordance with AWS SAM are JSON or YAML formatted text files. These files are CloudFormation templates.
AWS SAM introduces several new resources and property types that can be embedded into the Resources section of the template. The templates may include all other template sections and use CloudFormation intrinsic functions to access properties available only at runtime.
In order to include objects defined by AWS SAM within a CloudFormation template, the template must include a Transform section in the document root with a value of AWS::Serverless-2016-10-31.
Example: AWS SAM template
AWSTemplateFormatVersion: '2010-09-09'
Transform: 'AWS::Serverless-2016-10-31'
Resources:
MyFunction:
Type: 'AWS::Serverless::Function'
Properties:
Handler: index.handler
Runtime: nodejs4.3
CodeUri: 's3://my-bucket/function.zip'All property names in AWS SAM are case sensitive.
Resource types
AWS::Serverless::Function
Creates a Lambda function, IAM execution role, and event source mappings which trigger the function.
Properties
| Property Name | Type | Description |
|---|---|---|
| Handler | string |
Required. Function within your code that is called to begin execution. |
| Runtime | string |
Required. The runtime environment. |
| CodeUri | string |
Required. S3 Uri to the function code. The S3 object this Uri references MUST be a Lambda deployment package. |
| Description | string |
Description of the function. |
| MemorySize | integer |
Size of the memory allocated per invocation of the function in MB. Defaults to 128. |
| Timeout | integer |
Maximum time that the function can run before it is killed in seconds. Defaults to 3. |
| Role | string |
ARN of an IAM role to use as this function's execution role. If omitted, a default role is created for this function. |
| Policies | string | List of string | IAM policy document object | List of IAM policy document object |
Names of AWS managed IAM policies or IAM policy documents that this function needs, which should be appended to the default role for this function. If the Role property is set, this property has no meaning. |
| Environment | Function environment object | Configuration for the runtime environment. |
| VpcConfig | VPC config object | Configuration to enable this function to access private resources within your VPC. |
| Events | Map of string to Event source object |
A map (string to Event source object) that defines the events that trigger this function. Keys are limited to alphanumeric characters. |
Return values
Ref
When the logical ID of this resource is provided to the Ref intrinsic function, it returns the resource name of the underlying Lambda function.
Fn::GetAtt
When the logical ID of this resource is provided to the Fn::GetAtt intrinsic function, it returns a value for a specified attribute of this type. This section lists the available attributes.
| Attribute Name | Description |
|---|---|
| Arn | The ARN of the Lambda function. |
Example: AWS::Serverless::Function
Handler: index.js
Runtime: nodejs4.3
CodeUri: 's3://my-code-bucket/my-function.zip'
Description: Creates thumbnails of uploaded images
MemorySize: 1024
Timeout: 15
Policies: AmazonS3FullAccess
Environment:
Variables:
TABLE_NAME: my-table
Events:
PhotoUpload:
Type: S3
Properties:
Bucket: my-photo-bucketAWS::Serverless::Api
Creates a collection of Amazon API Gateway resources and methods that can be invoked through HTTPS endpoints.
An AWS::Serverless::Api resource need not be explicitly added to a AWS Serverless Application Definition template. A resource of this type is implicitly created from the union of Api events defined on AWS::Serverless::Function resources defined in the template that do not refer to an AWS::Serverless::Api resource. An AWS::Serverless::Api resource should be used to define and document the API using Swagger, which provides more ability to configure the underlying Amazon API Gateway resources.
Properties
| Property Name | Type | Description |
|---|---|---|
| StageName | string |
Required The name of the stage, which API Gateway uses as the first path segment in the invoke Uniform Resource Identifier (URI). |
| DefinitionUri | string |
Required S3 URI to the Swagger document describing the API. |
| CacheClusterEnabled | boolean |
Indicates whether cache clustering is enabled for the stage. |
| CacheClusterSize | string |
The stage's cache cluster size. |
| Variables | Map of string to string |
A map (string to string map) that defines the stage variables, where the variable name is the key and the variable value is the value. Variable names are limited to alphanumeric characters. Values must match the following regular expression: [A-Za-z0-9._~:/?#&=,-]+. |
Return values
Ref
When the logical ID of this resource is provided to the Ref intrinsic function, it returns the resource name of the underlying API Gateway RestApi.
Example: AWS::Serverless::Api
StageName: prod
DefinitionUri: swagger.ymlAWS::Serverless::SimpleTable
The AWS::Serverless::SimpleTable resource creates a DynamoDB table with a single attribute primary key. It is useful when data only needs to be accessed via a primary key. To use the more advanced functionality of DynamoDB, use an AWS::DynamoDB::Table resource instead.
Properties
| Property Name | Type | Description |
|---|---|---|
| PrimaryKey | Primary Key Object | Attribute name and type to be used as the table's primary key. This cannot be modified without replacing the resource. Defaults to String attribute named ID. |
| ProvisionedThroughput | Provisioned Throughput Object | Read and write throughput provisioning information. Defaults to 5 read and 5 write capacity units per second. |
Return values
Ref
When the logical ID of this resource is provided to the Ref intrinsic function, it returns the resource name of the underlying DynamoDB table.
Example: AWS::Serverless::SimpleTable
PrimaryKey:
Name: id
Type: String
ProvisionedThroughput:
ReadCapacityUnits: 5
WriteCapacityUnits: 5Event source types
S3
The object describing an event source with type S3.
Properties
| Property Name | Type | Description |
|---|---|---|
| Bucket | string |
Required. S3 bucket name. |
| Events | string | List of string |
Required. See Amazon S3 supported event types for valid values. |
| Filter | Amazon S3 notification filter | Rules to filter events on. |
NOTE: To specify an S3 bucket as an event source for a Lambda function, both resources have to be declared in the same template. AWS SAM does not support specifying an existing bucket as an event source.
Example: S3 event source object
Bucket: my-photo-bucket
Events: s3:ObjectCreated:*SNS
The object describing an event source with type SNS.
Properties
| Property Name | Type | Description |
|---|---|---|
| Topic | string |
Required. Topic ARN. |
Example: SNS event source object
Topic: arn:aws:sns:us-east-1:123456789012:my_topicKinesis
The object describing an event source with type Kinesis.
Properties
| Property Name | Type | Description |
|---|---|---|
| Stream | string |
Required. ARN of the Amazon Kinesis stream. |
| StartingPosition | string |
Required. One of TRIM_HORIZON or LATEST. |
| BatchSize | integer |
Maximum number of stream records to process per function invocation. |
Example: Kinesis event source object
Stream: arn:aws:kinesis:us-east-1:123456789012:stream/my-stream
StartingPosition: TRIM_HORIZON
BatchSize: 10DynamoDB
The object describing an event source with type DynamoDB.
Properties
| Property Name | Type | Description |
|---|---|---|
| Stream | string |
Required. ARN of the DynamoDB stream. |
| StartingPosition | string |
Required. One of TRIM_HORIZON or LATEST. |
| BatchSize | integer |
Maximum number of stream records to process per function invocation. |
Example: DynamoDB event source object
Stream: arn:aws:dynamodb:us-east-1:123456789012:table/TestTable/stream/2016-08-11T21:21:33.291
StartingPosition: TRIM_HORIZON
BatchSize: 10Api
The object describing an event source with type Api.
If an AWS::Serverless::Api resource is defined, the path and method values MUST correspond to an operation in the Swagger definition of the API. If no AWS::Serverless::Api is defined, the function input and output are a representation of the HTTP request and HTTP response.
Properties
| Property Name | Type | Description |
|---|---|---|
| Path | string |
Required. Uri path for which this function is invoked. MUST start with /. |
| Method | string |
Required. HTTP method for which this function is invoked. |
| RestApiId | string |
Identifier of a RestApi resource which MUST contain an operation with the given path and method. Typically, this is set to reference an AWS::Serverless::Api resource defined in this template. If not defined, a default AWS::Serverless::Api resource is created using a generated Swagger document contains a union of all paths and methods defined by Api events defined in this template that do not specify a RestApiId. |
Example: Api event source object
Path: /photos
Method: postSchedule
The object describing an event source with type Schedule.
Properties
| Property Name | Type | Description |
|---|---|---|
| Schedule | string |
Required. Schedule expression, which MUST follow the schedule expression syntax rules. |
| Input | string |
JSON-formatted string to pass to the function as the event body. |
Example: Schedule event source object
Schedule: rate(5 minutes)CloudWatchEvent
The object describing an event source with type CloudWatchEvent.
Properties
| Property Name | Type | Description |
|---|---|---|
| Pattern | Event Pattern Object | Required. Pattern describing which CloudWatch events trigger the function. Only matching events trigger the function. |
| Input | string |
JSON-formatted string to pass to the function as the event body. This value overrides the matched event. |
| InputPath | string |
JSONPath describing the part of the event to pass to the function. |
Example: CloudWatchEvent event source object
Pattern:
detail:
state:
- terminatedIoTRule
The object describing an event source with type IoTRule.
Properties
| Property Name | Type | Description |
|---|---|---|
| Sql | string |
Required. The SQL statement that queries the topic. For more information, see Rules for AWS IoT in the AWS IoT Developer Guide. |
| AwsIotSqlVersion | string |
The version of the SQL rules engine to use when evaluating the rule. |
Example: IoTRule event source object
Sql: "SELECT * FROM 'iot/test'"AlexaSkill
The object describing an event source with type AlexaSkill.
Specifying AlexaSkill event creates a resource policy that allows the Amazon Alexa service to call your Lambda function. To configure the Alexa service to work with your Lambda function, go to the Alexa Developer portal.
Property types
Environment object
The object describing the environment properties of a function.
Properties
| Property Name | Type | Description |
|---|---|---|
| Variables | Map of string to string |
A map (string to string map) that defines the environment variables, where the variable name is the key and the variable value is the value. Variable names are limited to alphanumeric characters and the first character must be a letter. Values are limited to alphanumeric characters and the following special characters _(){}[]$*+-\/"#',;.@!?. |
Example: Environment object
Variables:
TABLE_NAME: my-table
STAGE: prodEvent source object
The object describing the source of events which trigger the function.
Properties
| Property Name | Type | Description |
|---|---|---|
| Type | string |
Required. Event type. Event source types include 'S3, 'Api', 'SNS', 'Kinesis', 'DynamoDB'. For more information about all types, see Event source types. |
| Properties | * | Required. Object describing properties of this event mapping. Must conform to the defined Type. For more information about all types, see Event source types. |
Example: Event source object
Type: S3
Properties:
Bucket: my-photo-bucketType: AlexaSkillPrimary key object
The object describing the properties of a primary key.
Properties
| Property Name | Type | Description |
|---|---|---|
| Name | string |
Attribute name of the primary key. Defaults to id. |
| Type | string |
Attribute type of the primary key. MUST be one of String, Number, or Binary. |
Example: Primary key object
Name: id
Type: String