AWS Lambda Handler Cookbook (Python)

This project provides a working, open source based, AWS Lambda handler skeleton Python code including DEPLOYMENT code with CDK and a pipeline.

This project can serve as a template for new Serverless services - CDK deployment code, pipeline and handler are covered.

📜Documentation | Blogs website

Contact details | ran.isenberg@ranthebuilder.cloud

Getting Started

You can start with a clean service out of this template repository without using the 'Template' button on GitHub.

You can use Cookiecutter.

• Cookiecutter - install with pip/brew brew install cookiecutter or pip install cookiecutter

Then run:

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

Answer the questions to select repo name, service name, etc.:

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.

The Problem

Starting a Serverless service can be overwhelming. You need to figure out many questions and challenges that have nothing to do with your business domain:

• How to deploy to the cloud? What IAC framework do you choose?
• How to write a SaaS-oriented CI/CD pipeline? What does it need to contain?
• How do you handle observability, logging, tracing, metrics?
• How do you write a Lambda function?
• How do you handle testing?
• What makes an AWS Lambda handler resilient, traceable, and easy to maintain? How do you write such a code?

The Solution

This project aims to reduce cognitive load and answer these questions for you by providing a skeleton Python Serverless service template that implements best practices for AWS Lambda, Serverless CI/CD, and AWS CDK in one template project.

Concepts

I spoke at AWS re:invent 2023 with Heitor Lessa, Chief Architect of Powertools for AWS Lambda about the concepts I implemented in this project.

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 Pydantic 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
• Automated protection against API breaking changes

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
• Serverless OpenAPI Documentation with AWS Powertools

Getting started

Head over to the complete project documentation pages at GitHub pages at https://ran-isenberg.github.io/aws-lambda-handler-cookbook

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: IsenbergRan

Credits

• AWS Lambda Powertools (Python)

License

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