Menu
AWS Lambda
Developer Guide

Deploying Lambda-based Applications

Lambda-based applications (also referred to as serverless applications) are composed of functions triggered by events. A typical serverless application consists of one or more 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 DynamoDB tables or Amazon S3 buckets. The most basic serverless application is simply a function.

AWS Lambda provides API operations that you can use to create and update Lambda functions by providing a deployment package as a ZIP file. However, this mechanism might not be convenient for automating deployment steps for functions, or coordinating deployments and updates to other elements of a serverless application (like event sources and downstream resources). For example, in order to deploy an Amazon SNS trigger, you need to update the function, the Amazon SNS topic, the mapping between the function and the topic, and any other downstream resources required by your function such as a DynamoDB table.

Deploying Serverless Applications Using AWS CloudFormation

You can use AWS CloudFormation to specify, deploy, and configure serverless applications. AWS CloudFormation is a service that helps you model and set up your AWS resources so that you can spend less time managing those resources and more time focusing on your applications that run in AWS. You create a template that describes all of the AWS resources that you want (like Lambda functions and DynamoDB tables), and AWS CloudFormation takes care of provisioning and configuring those resources for you. You don't need to individually create and configure AWS resources and figure out what's dependent on what—AWS CloudFormation handles all of that. For more information, see AWS CloudFormation Concepts in the AWS CloudFormation User 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 CloudFormation

AWS SAM supports special resource types that simplify how to express functions, APIs, mappings, and DynamoDB tables for serverless applications, as well as some features for these services like environment variables. The AWS CloudFormation description of these resources conforms to the AWS Serverless Application Model. In order to deploy your application, simply specify the resources you need as part of your application, along with their associated permissions policies in an AWS CloudFormation template file (written in either JSON or YAML), package your deployment artifacts, and deploy the template.

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

The examples below illustrate how to leverage AWS SAM to declare common components of a serverless application:

Lambda function

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

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

    FunctionName:
        Type: AWS::Serverless::Function
        Properties:
           Handler: index.handler
           Runtime: nodejs4.3
           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.

AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Resources:
  PutFunction:
    Type: AWS::Serverless::Function
    Properties:
      Handler: index.handler
      Runtime: nodejs4.3
      Policies: AWSLambdaDynamoDBExecutionRole
      CodeUri: s3://bucketName/codepackage.zip
      Environment:
        Variables:
          TABLE_NAME: !Ref Table
  DeleteFunction:
    Type: AWS::Serverless::Function
    Properties:
      Handler: index.handler
      Runtime: nodejs4.3
      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:

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:

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:

AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Resources:
  FunctionName:
    Type: AWS::Serverless::Function
    Properties:
      Handler: index.handler
      Runtime: nodejs4.3
      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 above, you can set multiple event sources that will trigger the Lambda function. The example below 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:


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.


AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Resources:
  GetFunction:
    Type: AWS::Serverless::Function
    Properties:
      Handler: index.get
      Runtime: nodejs4.3
      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: nodejs4.3
      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: nodejs4.3
      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 above, 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 IAM role ARN to be used as this function's execution role, as shown below:


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.


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 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.