AWS Serverless service cookiecutter (Python)

This project can serve as a cookiecutter template for new Serverless services - CDK deployment code, pipeline and handler are covered with best practices built in.

The project is based on my AWS Lambda Cookbook template project:

Prerequisites

• Docker - install Docker. Required for the Lambda layer packaging process.
• AWS CDK - Required for synth & deploying the AWS Cloudformation stack.
• Python 3.13
• poetry - Make sure to run poetry config --local virtualenvs.in-project true so all dependencies are installed in the project '.venv' folder.
• For Windows based machines, use the Makefile_windows version (rename to Makefile). Default Makefile is for Mac/Linux.
• Cookiecutter - install with pip/brew brew install cookiecutter or pip install cookiecutter
  
  

Getting Started

cookiecutter gh:ran-isenberg/cookiecutter-serverless-python

Follow the cookiecutter questions:

That's it, your developer environment has been set! you are ready to deploy the service:

cd {new repo folder}
poetry shell
make deploy

You can also run 'make pr' will run all checks, synth, file formatters , unit tests, deploy to AWS and run integration and E2E tests.

For more information head over to project documentation pages at https://ran-isenberg.github.io/aws-lambda-handler-cookbook

The documentation provides information about CDK deployment, makefile commands, testing methodology and more.

Serverless Service - The Order service

• This project provides a working orders service where customers can create orders of items.

• The project deploys an API GW with an AWS Lambda integration under the path POST /api/orders/ and stores data in a DynamoDB table.

Monitoring Design

Features

• Python Serverless service with a recommended file structure.
• CDK infrastructure with infrastructure tests and security tests.
• CI/CD pipelines based on Github actions that deploys to AWS with python linters, complexity checks and style formatters.
• CI/CD pipeline deploys to dev/staging and production environments with different gates between each environment
• Makefile for simple developer experience.
• The AWS Lambda handler embodies Serverless best practices and has all the bells and whistles for a proper production ready handler.
• AWS Lambda handler uses AWS Lambda Powertools.
• AWS Lambda handler 3 layer architecture: handler layer, logic layer and data access layer
• Features flags and configuration based on AWS AppConfig
• Idempotent API
• REST API protected by WAF with four AWS managed rules in production deployment
• CloudWatch dashboards - High level and low level including CloudWatch alarms
• Unit, infrastructure, security, integration and end to end tests.
• Automatically generated OpenAPI endpoint: /swagger with Pydnatic schemas for both requests and responses
• CI swagger protection - fails the PR if your swagger JSON file (stored at docs/swagger/openapi.json) is out of date
  
  

CDK Deployment

The CDK code create an API GW with a path of /api/orders which triggers the lambda on 'POST' requests.

The AWS Lambda handler uses a Lambda layer optimization which takes all the packages under the [packages] section in the Pipfile and downloads them in via a Docker instance.

This allows you to package any custom dependencies you might have, just add them to the Pipfile under the [packages] section.

Serverless Best Practices

The AWS Lambda handler will implement multiple best practice utilities.

Each utility is implemented when a new blog post is published about that utility.

The utilities cover multiple aspect of a production-ready service, including:

• Logging
• Observability: Monitoring and Tracing
• Observability: Business KPIs Metrics
• Environment Variables
• Input Validation
• Dynamic Configuration & feature flags
• Start Your AWS Serverless Service With Two Clicks
• CDK Best practices
• Serverless Monitoring
• API Idempotency

Makefile Commands

Creating a Developer Environment

1. Run make dev
2. Run poetry install

Deploy CDK

Create a cloudformation stack by running make deploy.

Unit Tests

Unit tests can be found under the tests/unit folder.

You can run the tests by using the following command: make unit.

Integration Tests

Make sure you deploy the stack first as these tests trigger your lambda handler LOCALLY but they can communicate with AWS services.

These tests allow you to debug in your IDE your AWS Lambda function.

Integration tests can be found under the tests/integration folder.

You can run the tests by using the following command: make integration.

E2E Tests

Make sure you deploy the stack first.

E2E tests can be found under the tests/e2e folder.

These tests send a 'POST' message to the deployed API GW and trigger the Lambda function on AWS.

The tests are run automatically by: make e2e.

Deleting the stack

CDK destroy can be run with make destroy.

Preparing Code for PR

Run make pr. This command will run all the required checks, pre commit hooks, linters, code formats, flake8 and tests, so you can be sure GitHub's pipeline will pass.

The command auto fixes errors in the code for you.

If there's an error in the pre-commit stage, it gets auto fixed. However, are required to run make pr again so it continues to the next stages.

Be sure to commit all the changes that make pr does for you.

Code Contributions

Code contributions are welcomed. Read this guide.

Code of Conduct

Read our code of conduct here.

Connect

• Email: ran.isenberg@ranthebuilder.cloud
• Blog Website RanTheBuilder
• LinkedIn: ranisenberg
• Twitter: RanBuilder
  
  

Credits

• AWS Lambda Powertools (Python)
  
  

License

This library is licensed under the MIT License. See the LICENSE file.