In this post I'll highlight the minimum number of steps to get up and running with SAM Local.
SAM Local builds upon AWS SAM: The Serverless Application Model. It was introduced in late 2016 and presents a simplified model for creating and deploying serverless applications. Oh, and the mascot is a magic construction squirrel:
It's a transformation layer on top of AWS CloudFormation that gives you a declarative way to define your serverless resources.
Using SAM instead of raw CloudFormation allows for a less verbose declaration of resources such as functions (Lambda), event sources (e.g. S3, API Gateway, etc), and database (DynamoDB).
A potential point of confusion for new users of SAM is that it is an open source standard, not an open source tool. While you can suggest and submit improvements to the standard (via the GitHub repo), the actual implementation is not open (because it depends on CloudFormation, which is an AWS service).
It's also important to note that SAM will not support non-serverless services. If you want to create other resources, just use CloudFormation in your SAM template! It all gets translated to CloudFormation in the end...
In order to get started you'll need to have Docker running in the background. On Mac OSX you should install that via Homebrew:
brew cask install docker
Once installed and run, you'll see the Docker icon in your tray, and it should be running:
Now that you've got the required dependencies, install the SAM Local tool itself:
npm install --global aws-sam-local
Once that's installed, you can access the command
sam in your terminal.
To get started quickly we'll leverage the
api-event-source sample projects in the SAM Local repo.
Clone the repo and go to the example directory:
git clone https://github.com/awslabs/aws-sam-local.git
This project creates a single function with an API (i.e. HTTP) event source, so it simulates a Lambda function and an API Gateway endpoint.
At the top of the
template.yaml file you can see the key difference with normal CloudFormation templates:
AWSTemplateFormatVersion : '2010-09-09'
Transform property tells CloudFormation how to handle the template, and allows you to use the SAM resource types.
All the function handler code (in
index.js) does is return a 200 response with the string payload "OK".
sam local start-api
If it's the first time you've run this command, the Docker container will be downloaded before running.
In the output you'll see the required container being run, and then listening for events as a HTTP endpoint that you can open in your local browser.
On my development laptop it took a while for requests to respond, even though the actual compute time of the function (which is reported in the output) was very low:
2017/08/16 22:22:14 Invoking index.handler (nodejs6.10)
START RequestId: 0d3c5d51-c16e-19a9-2816-78fdeffb2f51 Version: $LATEST
END RequestId: 0d3c5d51-c16e-19a9-2816-78fdeffb2f51
REPORT RequestId: 0d3c5d51-c16e-19a9-2816-78fdeffb2f51 Duration: 8.15 ms Billed Duration: 100 ms Memory Size: 128 MB Max Memory Used: 29 MB
This is because of the overhead of spinning up the container (before it even touches your code) for each request. I found that giving the function more memory (the default is the lowest i.e. 124MB) sped up effective response time considerably. Hopefully that (i.e. cold starts) is something that can be improved in the future without having to throw memory at it.
If you only edit your function handler code (i.e. in
index.js) you don't need to restart your service.
Changes to the template (i.e.
template.yaml) do need a restart to take effect.
Before I would usually have to set up a logging function (i.e. one that just logs the event it receives to the console) with my chosen event source, and fire a few test events to it so that I had something to work with.
Now we can just run a command locally to get a sample event to work with. In this case we want an API test event, so we pass that as an argument:
sam local generate-event api
This will output the event (JSON) to your terminal. While interesting, it's not usable.
To save it so we can use it later, redirect the output to a file:
sam local generate-event api > event.json
Now that we have a test event, we can do a one-off invocation of our function with the test event we've saved:
sam local invoke "ExampleFunction" -e event.json
This will give the function's output as a one-off.
START RequestId: 42949c86-df9a-1f85-6ed3-c399223e292f Version: $LATEST
END RequestId: 42949c86-df9a-1f85-6ed3-c399223e292f
REPORT RequestId: 42949c86-df9a-1f85-6ed3-c399223e292f Duration: 11.16 ms Billed Duration: 100 ms Memory Size: 128 MB Max Memory Used: 28 MB
Any errors will be output to
Another one of the great time-saving features I was happy to see in SAM Local was the
If your template is using SAM (i.e. not just CloudFormation) and named
template.yaml you can validate it with:
This will give you feedback on your template's properties and formatting (e.g. YAML whitespace) without going through the package/deploy/test cycle, which is a big improvement to the development flow.
All the commands take the
--help argument so that you can find out all their valid arguments and descriptions.
I'm really happy that the tooling around serverless applications is improving at such a rapid clip!