Concepts

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

Getting Started

You can start with a clean service out of this blueprint 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}
uv sync
make deploy

Make sure you have uv installed.

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 blueprint that implements best practices for AWS Lambda, Serverless CI/CD, and AWS CDK in one blueprint project.

Serverless Service - The Order service

• This project provides a working orders service where customers can create, get, and delete orders of items.

• The project deploys an API GW with AWS Lambda integrations and stores data in a DynamoDB table:

  • POST /api/orders/ - Create a new order
  • GET /api/orders/{order_id} - Get an order by ID
  • DELETE /api/orders/{order_id} - Delete an order by ID
  • GET /api/orders/?limit={n}&next_token={cursor} - List orders with pagination, served by an AWS Lambda Managed Instances pool

flowchart LR
    subgraph AWS["AWS Cloud"]
        subgraph APIGW["API Gateway"]
            REST["REST API<br/>POST /api/orders<br/>GET /api/orders/{id}<br/>GET /api/orders (list)<br/>DELETE /api/orders/{id}"]
        end

        subgraph Security["Security (Production)"]
            WAF["WAF WebACL<br/>AWS Managed Rules"]
        end

        subgraph Compute["Compute"]
            CREATE["Create Order<br/>Lambda Function"]
            GET["Get Order<br/>Lambda Function"]
            DELETE["Delete Order<br/>Lambda Function"]
            LAYER["Lambda Layer<br/>Common Dependencies"]
        end

        subgraph LMI["Lambda Managed Instances (VPC)"]
            LIST_ALIAS["ListOrders Alias: live"]
            LIST["List Orders<br/>Lambda Function"]
            CP["Capacity Provider<br/>EC2 pool, 2 AZs"]
        end

        subgraph Config["Configuration"]
            APPCONFIG["AppConfig<br/>Feature Flags"]
        end

        subgraph Storage["Storage"]
            DDB[("DynamoDB<br/>Orders Table")]
            IDEMPOTENCY[("DynamoDB<br/>Idempotency Table")]
        end
    end

    CLIENT((Client)) --> WAF
    WAF --> REST
    REST --> CREATE
    REST --> GET
    REST --> DELETE
    REST --> LIST_ALIAS
    LIST_ALIAS --> LIST
    LIST -.runs on.-> CP
    CREATE --> LAYER
    GET --> LAYER
    DELETE --> LAYER
    CREATE --> APPCONFIG
    CREATE --> DDB
    CREATE --> IDEMPOTENCY
    GET --> DDB
    DELETE --> DDB
    LIST --> DDB

    style CLIENT fill:#f9f,stroke:#333
    style WAF fill:#ff6b6b,stroke:#333
    style REST fill:#4ecdc4,stroke:#333
    style CREATE fill:#ffe66d,stroke:#333
    style GET fill:#ffe66d,stroke:#333
    style DELETE fill:#ffe66d,stroke:#333
    style LAYER fill:#ffe66d,stroke:#333
    style LIST fill:#ffa500,stroke:#333
    style LIST_ALIAS fill:#4ecdc4,stroke:#333
    style CP fill:#ff6b6b,stroke:#333
    style APPCONFIG fill:#95e1d3,stroke:#333
    style DDB fill:#4a90d9,stroke:#333
    style IDEMPOTENCY fill:#4a90d9,stroke:#333

LIST orders via AWS Lambda Managed Instances

The GET /api/orders/ endpoint is deliberately powered by AWS Lambda Managed Instances (LMI) rather than standard Lambda. LMI maintains a warm pool of execution environments on an EC2-backed capacity provider, so paginated list traffic avoids cold starts, runs inside a private VPC with DynamoDB and observability VPC endpoints, and can cap concurrency per environment (useful for bounding DynamoDB Scan pressure). The CRUD endpoints stay on standard Lambda — LMI is picked per-function, only where its extra surface area pays off.

See the Lambda Managed Instances deep-dive for tuning knobs (memory-to-vCPU ratio, min/max environments, per-env concurrency), the matching CDK construct, and the gotchas around version publishing and memory/CPU constraints.

Monitoring Design

flowchart TB
    subgraph Monitoring["CloudWatch Monitoring"]
        subgraph Dashboards["Dashboards"]
            HL["High-Level Dashboard<br/>API Gateway Metrics<br/>Business KPIs"]
            LL["Low-Level Dashboard<br/>Lambda Metrics<br/>DynamoDB Metrics"]
        end

        subgraph Alarms["CloudWatch Alarms"]
            API_ALARM["API Gateway Alarms<br/>5XX Errors, Latency"]
            LAMBDA_ALARM["Lambda Alarms<br/>Errors, P90 Latency"]
            DDB_ALARM["DynamoDB Alarms<br/>Throttles, Errors"]
        end
    end

    subgraph Notification["Notification"]
        SNS["SNS Topic<br/>KMS Encrypted"]
    end

    subgraph Resources["Monitored Resources"]
        APIGW["API Gateway"]
        LAMBDA["Lambda Function"]
        DDB["DynamoDB Tables"]
    end

    APIGW --> API_ALARM
    LAMBDA --> LAMBDA_ALARM
    DDB --> DDB_ALARM

    API_ALARM --> SNS
    LAMBDA_ALARM --> SNS
    DDB_ALARM --> SNS

    API_ALARM --> HL
    LAMBDA_ALARM --> LL
    DDB_ALARM --> LL

    style HL fill:#4ecdc4,stroke:#333
    style LL fill:#4ecdc4,stroke:#333
    style SNS fill:#ff6b6b,stroke:#333
    style API_ALARM fill:#ffe66d,stroke:#333
    style LAMBDA_ALARM fill:#ffe66d,stroke:#333
    style DDB_ALARM fill:#ffe66d,stroke:#333

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
• Automatic GitHub releases with semantic versioning based on conventional commits
• Automatic PR labeling based on commit message prefixes (feat, fix, docs, chore)
• 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
• AWS Lambda Managed Instances pool powers the paginated LIST endpoint (VPC, capacity provider, warm environments)

CDK Deployment

The CDK code creates an API GW with paths /api/orders (POST) and /api/orders/{order_id} (GET, DELETE), each backed by a dedicated Lambda function.

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](https://ranthebuilder.cloud/blog/aws-lambda-cookbook-elevate-your-handler-s-cod