A test project demonstrating how to publish your lambdas to a localstack instance
- Docker and docker compose
- Localstack; our AWS simulator (used in the optional challenges)
- AWS SAM CLI
- NodeJS
Localstack is our AWS simulator, find out more here. For this guide we're interested in the fact that localstack can run Lambdas locally.
In the root of the project we have a docker compose file. Here we've defined how to boot the localstack docker image. Open a terminal in the project dir and run
docker-compose up -dSo what are we working with? In the src/handlers dir we have two lambdas defined; the get-user and replay-event functions.
This function is exposed via a REST endpoint. Calling with a id query param of 1 returns the user John Smith. Calling with any other value for id returns a user not found error. Specifying no query param also returns an error.
This is a very simple function. Passing an event to it returns the same event wrapped up.
We have some basic unit tests for these lambdas. Lets ensure everything is working. Lets install our dependencies and run those tests.
npm install
npm testIn the root of the project we have the formation template template.yml. This file defines the AWS services we want to deploy. We have the code we want to execute in src/handlers and the template.yml tells AWS how to run the code.
The formation template can be a comprehensive breakdown of how all of your services run and interconnect. For example you can define a lambda that exposed via API Gateway that's secured with Cognito with the lamda generating a message that gets dumped onto a SQA queue and so on and so forth. It can as simple or complex as you need.
Ours is the former. All ours does is define two lamdbas, one exposed via a REST GET request and the other not exposed via API. It defineds memory limit and timeouts along with the IAM roles to generated along side.
To do this we only need the AWS SAM CLI, we don't rely on localstack for this. Run the following command to invoke the ReplayEventFunction.
sam local invoke "ReplayEventFunction" -e events/event.jsonLet break that down
samwe're running the AWS SAM CLIlocalwe're telling sam to spin something up locallyinvoke "ReplayEventFunction"we're invoking a lamdba with the nameReplayEventFunction. This name is set in the formation template-e events/event.jsonUsing a json file from the events dir, we're calling the lambda with an event. This argument can be omitted to provide no event data.
You should see the result of the lambda invocation in the terminal output.
To do this we only need the AWS SAM CLI, we don't rely on localstack for this. Run the following command to invoke the GetUserFunction. Our GetUserFunction is configured to be exposed via API, but how do we do that locally? Let run the following command
sam local start-api -t template.yaml -p 3000Lets break this one down as well
samwe're running the AWS SAM CLIlocalwe're telling sam to spin something up locallystart-apitells sam to a local http server-t template.ymltells sam what formation template to use so sam knows how to setup your lambdas-p 3000tells sam what port to expose the local http server on
Now that your lambdas are deployed to localstack and are exposed on port 3000, try calling the endpoint using curl, wget or postman.
http://localhost:3000/accounts/user?id=1 Will return the user John Smith
http://localhost:3000/accounts/user?id=2 Will return a user not found error
http://localhost:3000/accounts/user Will return a no id param error- Following the code structure and formation template patterns seen here. Have a go at writing and deploying a lamdba with the AWS SAM CLI.
- Going even further. AWS offers so much than running lambdas. Try integrating your lambda with another AWS service running on localstack.
Want to extend this repo and provide more info on using AWS services locally? Fork and raise a PR, it will be reviewed and considered for merging.
This code is open source software licensed under the Apache 2.0 License