AWS have released a new tool in beta, SAM Local, that makes it easy to build and test serverless AWS Lambda applications on a local development machine. Core features provided by SAM Local include: the ability to test AWS Lambda functions locally running within Docker, a simple CLI to start a local API Gateway that fronts a Lambda function via a SAM template, validation of SAM templates, and the generation of sample payloads for testing the handling of various AWS event sources such as S3, Kinesis and CloudTrail.
AWS introduced the Serverless Application Model (SAM) last year with the goal of making it easier for developers to deploy serverless applications. SAM is an open source specification built upon and extending AWS CloudFormation, which is AWS's infrastructure as code (IaC) offering that allows developers to declaratively specify the deployment and configuration of cloud resources.
The main features of SAM Local include:
- Develop and test AWS Lambda functions locally with sam local and Docker.
- Simulate function invocations from known event sources like Amazon Simple Storage Service (S3), Amazon DynamoDB, Amazon Kinesis, Amazon Simple Notification Service (SNS), and more.
- Start a local Amazon API Gateway from a SAM template, and quickly iterate on the development of functions with hot-reloading.
- Quickly validate SAM templates, including integration with linters or IDEs.
- Provides interactive debugging support for Lambda functions.
Running Serverless projects and functions locally with SAM Local requires Docker to be installed and running, and SAM Local will use the DOCKER_HOST environment variable to contact the docker daemon. SAM Local can be installed through NPM (npm install -g aws-sam-local), or the latest version can be installed straight from source (go get github.com/awslabs/aws-sam-local which will create a binary named aws-sam-local, not sam).
Developers specify the deployment configuration of functions and associated integrated AWS resources by using an enhanced CloudFormation template format (that is ultimately transformed into a standard CloudFormation template). For example, the template.yaml file shown below defines a simple DynamoDB table, a Python-based Lambda function (the source code is included within a separate file with the name as specified in the 'Handler property' lambda_function.py), and an API Gateway instance with GET and POST methods supported.
AWSTemplateFormatVersion : '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Resources:
VotesTable:
Type: "AWS::Serverless::SimpleTable"
VoteSpacesTabs:
Type: "AWS::Serverless::Function"
Properties:
Timeout: 30
Runtime: python3.6
Handler: lambda_function.lambda_handler
Policies: AmazonDynamoDBFullAccess
Environment:
Variables:
TABLE_NAME: !Ref VotesTable
Events:
GetVotes:
Properties:
Method: get
Path: /
Type: Api
Vote:
Properties:
Method: post
Path: /
Type: Api
An AWS Blog post written by Randall Hunt contains an example SAM Deployment with API Gateway integration, and demonstrates how SAM Local assists with the development workflow. The instructions are comprehensive, but your correspondent did have to create the associated DynamoDB table before the function could be tested (an example 'create-table' command that can be issued via the AWS CLI is shown below), and when running a local DynamoDB for testing purposes also change the DynamoDB hostname within the function to be the machine's local network IP address, and not simply 'localhost', due to the fact that the function runs within a Docker container, which on Docker for Mac or Docker for Windows runs within its own VM where 'localhost' provides a different context.
--table-name spaces-tabs-votes \
--attribute-definitions \
AttributeName=id,AttributeType=S \
--key-schema AttributeName=id,KeyType=HASH \
--provisioned-throughput ReadCapacityUnits=1,WriteCapacityUnits=1 \
--endpoint-url http://localhost:8000
SAM local can generate AWS service events for testing purpose, for example, by issuing the following CLI command 'sam local generate-event <service>', and also allows interactive debugging via a supported IDE. In Java and Node.js the -d flag and a port can be passed to the 'sam local' CLI command to immediately enable the debugger. The AWS Blog suggests that for Python a library like epdb could be used.
Once a serverless application has been developed and tested locally, the SAM CLI can be used to package and deploy the application to a live environment. The 'sam package' command will zip the code artifacts, upload to S3 and produce a SAM file that is ready to be deployed to Lambda using AWS CloudFormation. The 'sam deploy' command will deploy the packaged SAM template to CloudFormation. Both 'sam package' and 'sam deploy' are identical to their AWS CLI equivalents commands aws cloudformation package and aws cloudformation deploy respectively.
Additional information on SAM local can be found on the AWS Blog "New - AWS SAM Local (Beta) - Build and Test Serverless Applications Locally" or within the project's GitHub repository.
