AWS Lambda Python Template

A template for creating AWS Lambda functions with Python, using Docker images stored in Amazon ECR. This template provides a solid starting point for building serverless applications on AWS, especially if you need:

• Both prod and dev environments that live within a VPC
• Connection to a MySQL database
• Integration with external APIs

Features

• Python 3.12: Uses a recent Python runtime compatible with AWS Lambda.
• Docker-based: Packages the Lambda function as a Docker image for consistency and portability.
• Dependency Management: Uses uv for fast and reliable dependency management.
• Linting and Formatting: Includes a pre-commit hook with ruff to ensure code quality.
• Secrets Management: Demonstrates how to use AWS Secrets Manager to handle sensitive information.
• Database Connectivity: Provides an example of how to connect to a MySQL database from a Lambda function.
• External API Calls: Shows how to make calls to external APIs.
• CI/CD: Includes example GitHub Actions workflows for continuous integration and deployment.

Project Structure

.
├── .github/workflows         # Example GitHub Actions workflows
├── cloudformation            # Example CloudFormation templates
├── models                    # Pydantic models for data validation
├── services                  # Business logic and external service integrations
├── utils                     # Utility functions (e.g., logger, config)
├── .pre-commit-config.yaml   # Configuration for pre-commit hooks
├── debug_lambda.py           # Script for running the Lambda function locally
├── lambda_function.py        # The main Lambda function handler
├── pyproject.toml            # Project metadata and dependencies
└── README.md                 # This file

Getting Started

Prerequisites

• AWS CLI
• Docker
• Python 3.12
• uv

Local Development

1. Clone the repository:

   git clone https://github.com/your-username/aws-lambda-python-template.git
   cd aws-lambda-python-template

2. Install dependencies:

   uv sync

3. Set up environment variables:

   Create a .env file in the root of the project and add the following variables:

   AWS_SECRET_NAMES=your-secret-name
   X_API_KEY=your-api-key
   NASA_API_KEY=DEMO_KEY

   • AWS_SECRET_NAMES: The name of the secret in AWS Secrets Manager that holds your database credentials and other secrets.
   • X_API_KEY: An API key to protect your Lambda function when it's exposed via API Gateway.
   • NASA_API_KEY: The template uses the NASA APOD API for a fun demonstration of external API calls. You can use DEMO_KEY for basic testing.

You can then use a mix and match with .env and AWS Secrets Manager to manage your secrets.

4. Run the Lambda function locally:

   The debug_lambda.py script provides a way to run the Lambda function locally and use the .env file to load environment variables (or alternatively pull from AWS Secrets Manager).

   TESTING=1 uv run debug_lambda.py

AWS Infrastructure (Example)

The cloudformation directory contains an example CloudFormation template (ecr-lambda-stack.yaml) that creates the necessary AWS resources for this project. This is just an example, and you can modify it to fit your needs.

Resources

• Amazon ECR Repository: To store the Docker image for the Lambda function.
• AWS Lambda Function: The serverless function itself.
• IAM Roles and Policies: To grant the Lambda function the necessary permissions.

CI/CD Workflow (Example)

The template includes example GitHub Actions workflows in the .github/workflows directory for building and deploying the Lambda function.

• quality-checks.yaml: Runs linting and formatting checks on pull requests to ensure code quality.
• create-release.yaml: Manually triggered to create new releases. It bumps the version, creates a GitHub release, and tags the code.
• build-deploy-lambda.yaml: Triggered automatically when a release is published. It builds the Docker image, pushes it to ECR, and updates the Lambda function.

These workflows are meant to be a starting point and can be customized to fit your deployment strategy.

Using the GitHub Actions workflows

Opening a pull request

When you open a pull request, the quality-checks.yaml workflow will run automatically to validate your changes.

Creating a release

1. Go to the Actions tab in your GitHub repository.
2. Select the Create and Publish Release workflow.
3. Click Run workflow.
4. Choose the version bump type (patch, minor, or major) and the branch to release from.
5. Click Run workflow.

This will create a new release and trigger the deployment workflow.

Manual deployment (Optional)

You can also manually deploy the Lambda function:

1. Go to the Actions tab in your GitHub repository.
2. Select the Deploy to ECR-Lambda on Release workflow.
3. Click Run workflow.
4. Select the environment and other options.
5. Click Run workflow.

Customization

This template is designed to be easily customized. Here are a few things you might want to change:

• pyproject.toml: Update the project name, description, and dependencies.
• lambda_function.py: Modify the core logic of the Lambda function.
• cloudformation/ecr-lambda-stack.yaml: Adjust the AWS resources to match your requirements.
• .github/workflows: Customize the CI/CD workflows.