How to deploy SAM stack with localstack?

Question

I've written a SAM stack and I can build, package and deploy it on AWS. I can also use start-local or invoke to test. Now I need to test to other AWS resources. I've added those resources to my SAM template. It works well on AWS but I'm searching for a way to deploy my SAM stack in localstack (local dynamodb e.g.). Now I have to create the resources with the CLI and after that I can deploy my SAM stack (only lambda, API GW in this case). How can I do this?

Answer 1

I've just gone through this. I think the following is correct.

AWS SAM is a wrapper round Cloudformation. So your SAM template is actually a Cloudformation template. Your Cloudformation template defines your lambdas and dynamodb etc. When you deploy to AWS all of your lambdas and dynamodb go into AWS and you can test in the cloud.

When you run AWS SAM locally you run your lambda locally (in a docker container) but it still access resources in the AWS cloud.

LocalStack does have a CloudFormation interface, so it should be possible to deploy your CloudFormation template file. But I ran into a few issues with this and gave up.

Serverless Framework is similar to AWS SAM in that it is a framework to develop your serveless (lambda) code and to deploy that to AWS. Serverless has it's own yaml specification for defining a stack. Converting from Cloudformation to Serverless yaml is a little bit of work.

There is a serverless plugin for localstack. It is then possible to deploy your code to localstack. If you have API Gateway infront of your lambdas then there will be a local url you can hit which triggers your lambdas. This is fully within localstack and not using AWS SAM.

At this point you may find your code still hits the real AWS services. So you need to change the endpoint-url to point locally, as Andrew A. mentioned. For this, and to keep your code the same for test and production you can use environment variables for each of the service endpoints.

As Andrew A. mentions it should be possible to run code using SAM local which accesses resources provided by localstack. However, it may be preferrable to keep to one tool, if this was done within a testing pipeline say.

Answer 2

The makers of Localstack have created a lightweight wrapper for the sam cli. Simply use pip to install samlocal as a Python library on your machine:

pip install aws-sam-cli-local

You can then deploy to local stack using samlocal deploy in place of the regular sam deploy. Something like the following:

samlocal deploy --stack-name sam-app --capabilities CAPABILITY_IAM --guided

For further detail of the options available on sam deploy see the docs here.