Lambda API Template

AWS Lambda API template

A minimal template project that will get you up and running with an AWS API Gateway public endpoint that invokes a lambda function via proxy integration.

The project includes a basic bash cli that simplifies setup, development, and deployment commands.

Setup

• To begin, make the cli executable and run the setup command.

chmod +x cli.sh
./cli.sh setup

• Fill in the required environment variables defined in the config file that was generated by the setup.
• Ensure you have the AWS CDK cli installed.

npm install -g aws-cdk

Create an profile to be used by the AWS CDK and the cli tool.

• Create a new IAM user in the AWS console and give it programatic access (not console access). Give the new user the following roles:
  • AmazonS3FullAccess # For cdk bootstrap
  • AmazonSSMFullAccess # For cdk bootstrap
  • IAMFullAccess # For cdk bootstrap (fairly dangerous, beware!)
  • AmazonEC2ContainerRegistryFullAccess # For cdk bootstrap
  • AWSCloudFormationFullAccess # For cdk deploy
  • AmazonAPIGatewayAdministrator # For the application
  • AmazonDynamoDBFullAccess # For the application
  • AWSLambda_FullAccess # For the application
• Generate access keys for the IAM user and use them to configure an AWS CLI profile.

aws configure --profile cdk-user
# Provide the key and secret for your IAM user

Remember the name you used (“cdk-user” in this example) and put it in the config.py file under AWS_PROFILE, also configure the AWS_ACCOUNT and AWS_REGION variables.

# config.py
AWS_ACCOUNT = "12345678910"
AWS_REGION = "us-east-1"
AWS_PROFILE = "cdk-user"

• If you have not used cdk for the environment (account + region) you plan on deploying to - you need to run `cdk bootstrap`. The included cli provides a utility function to do this for you.

./cli.sh cdk_bootstrap

• Finally, modify the stack values in app.py, such as the resource names and ids, then build and deploy your application.

./cli.sh build
./cli.sh deploy

You’ll get the following output from deployment:

✅  CdkTestStack

✨  Deployment time: 26.71s

Outputs:
CdkTestStack.MyApiGatewayEndpointXXXXXXXX = https://xxxxxxx.execute-api.<<region>>.amazonaws.com/prod/

That url, plus your endpoint (default ‘endpoint’) is your public api endpoint. You could paste this in your browser or run a curl command to see it working.

# Add 'endpoint' or whatever you defined in the app.py, instead.
curl https://xxxxxxx.execute-api.<<region>>.amazonaws.com/prod/endpoint

Application Structure

Once deployed, you’ll have an AWS application with the following structure:

• API Gateway endpoint invoking a lambda function.
• A lambda function with access to a dynamodb table.
• A dynamodb table.

The included `cli.sh` includes functionality to quickly destroy all created resources as well as other helper functions. Run the cli without any arguments to get a detailed help message describing its functionality. Some functions you’ll be using most often:

• ./cli.sh build => this packages your python code into a package.zip.
• ./cli.sh deploy => this deploys your package.zip and infrastructure changes directly to your application.

Virtual environments

This project utilizes 2 virtual environments.

• .venv_dev: This is the development environment. It includes the cdk packages and whatever else is needed for development and deployment. Should you want to add unit tests you’d put your test library here. This env also includes ALL PROD dependancies.
• .venv_prod: This is the prod environment. It includes only what is required for the lambda function code. (Note: boto3 comes included with AWS Lambda, and so it is included in the dev environment for LSP/IDE purposes and any commands you might want to use in scripts)

You typically do not need to source these environments as the cli commands individually source whichever they need.

When selecting an interpreter for your development environment - select the dev venv.

Some notes

This is a minimal template to get you up and running as fast as possible with an API conviniently defined using the AWS CDK.

Should your project grow into a production application, you’d likely want to start using a CI/CD tool or pipeline; add unit and integration tests; and perhaps include a staging or onebox environment.

I hope this helps you quickly setup some new projects!

Contributing

I don’t imagine many people would want to contribute to my small template, but if you do - I’d be happy to review any PRs!