EasySAM

EasySAM is an opinionated YAML-to-SAM generator for modular AWS serverless applications.

It helps you define Lambda functions, API Gateway routes, DynamoDB tables, S3 buckets, SQS queues, Kinesis streams, OpenSearch Serverless collections, and IoT Core authorizers in a compact resources.yaml model, then generate and deploy the resulting SAM stack.

Why EasySAM

• Simple YAML-first resource definitions
• Recursive import system (import + local easysam.yaml)
• Modular app structure with shared common/ code support
• Built-in validation (inspect schema, inspect cloud)
• Native support for:
  • Environment variable expansion and .env loading
  • DynamoDB stream triggers from table definitions
  • DynamoDB TTL
  • Lambda Function URLs
  • Prismarine model-driven tables
  • OpenSearch Serverless search collections
  • MQTT/IoT Core custom authorizers
  • Local Lambda execution (no Docker required)

Prerequisites

• Python 3.12+ (Your local/CI environment version should match the python: option in resources.yaml to ensure dependency compatibility)
• AWS credentials configured (named profile recommended)
• AWS SAM CLI 1.138.0+
• pip 25.1.1+ (used in deployment checks)
• One of:
  • uv (recommended for project-local workflows)
  • pipx (recommended for global CLI install)
  • pip

Installation

Choose one installation method.

Option A: project-local with uv

uv add --dev easysam

Use as:

uv run easysam --help

Option B: global with pipx

pipx install easysam

Use as:

easysam --help

Option C: global/local with pip

pip install easysam

Quick start (5 minutes)

1. Create a Python project and initialize EasySAM:

mkdir my-easysam-app
cd my-easysam-app
uv init
uv add --dev easysam
uv run easysam init

For a Prismarine scaffold:

uv run easysam init --prismarine

2. Validate your resources:

uv run easysam --environment dev inspect schema .

3. Generate templates:

uv run easysam --environment dev generate .

4. Deploy to AWS:

uv run easysam --environment dev --aws-profile my-profile deploy . --tag project=easysam-demo

5. Delete stack when done:

uv run easysam --environment dev --aws-profile my-profile delete --await

For all options:

uv run easysam --help

Local execution

Run your Lambda handlers locally without deploying — no Docker required. EasySAM starts a local HTTP server that mocks API Gateway routing while using real cloud resources (DynamoDB, S3, etc.).

# Start local server (default: http://127.0.0.1:3000)
uv run easysam --environment dev local .

# Custom port and REST API v1 event format (default)
uv run easysam --environment dev local . --port 8080

# Use HTTP API v2 event format
uv run easysam --environment dev local . --event-format v2

# Inject authorization context (simulates authenticated user)
uv run easysam --environment dev local . --auth-context '{"principalId": "dev-user"}'

# Or from a file
uv run easysam --environment dev local . --auth-context auth-context.json

Then call your endpoints:

curl http://127.0.0.1:3000/items

Invoke a single function

For non-HTTP triggers (SQS, Kinesis, DynamoDB streams), invoke a function directly:

# With an event file
uv run easysam --environment dev local . invoke myfunction --event event.json

# With inline JSON
uv run easysam --environment dev local . invoke myfunction --event '{"Records": [...]}'

# With empty event (default)
uv run easysam --environment dev local . invoke myfunction

Minimal resources.yaml

prefix: MyApp

import:
  - backend

EasySAM recursively finds easysam.yaml files under backend/ and merges them.

Local import file format (easysam.yaml)

lambda:
  name: myfunction
  resources:
    tables:
      - MyItem
  integration:
    path: /items
    open: true
    greedy: false

You can also define tables locally:

tables:
  MyItem:
    attributes:
      - name: ItemID
        hash: true

Key concepts

Environment Variables and .env files

EasySAM automatically loads .env files if present in the target directory. It evaluates environment variables using the standard ${MY_VAR} syntax in both global (resources.yaml) and local (easysam.yaml) files immediately after they are loaded.

Global CLI options can also be set via environment variables:

Explicit CLI flags always take precedence over environment variables.

You can also pass environment variables to your functions directly using the envvars property.

functions:
  myfunc:
    uri: "src/"
    envvars:
      API_URL: "${API_URL}"
      LOG_LEVEL: "DEBUG"

DynamoDB table triggers

Trigger a Lambda directly from table changes:

tables:
  SearchableItem:
    attributes:
      - name: ItemID
        hash: true
    trigger: indexfunc

Advanced trigger configuration:

tables:
  SearchableItem:
    attributes:
      - name: ItemID
        hash: true
    trigger:
      function: indexfunc
      viewtype: new-and-old
      batchsize: 10
      batchwindow: 5
      startingposition: latest

Conditional resources

Conditional keys are resolved against deploy context (environment, target_region):

buckets:
  ? !Conditional
    key: my-bucket
    environment: prod
    region: eu-west-2
  :
    public: true
    extaccesspolicy: ProdPolicy

Negation is supported using ~ (example: environment: ~prod).

Deployment context overrides

Use a context file for CI/environment-specific patches:

overrides:
  buckets/my-bucket/public: true

Then pass it with:

uv run easysam --environment dev --context-file deploy-context.yaml deploy .

Prismarine integration

prismarine:
  default-base: common
  access-module: common.dynamo_access
  modelling: typed-dict
  tables:
    - package: myobject

Set modelling: pydantic for Pydantic-based generated clients.

MQTT / IoT Core custom authorizer

mqtt:
  authorizer:
    function: mqtt-auth
  topics:
    - channels/*

If a function publishes to IoT topics, add mqtt in function services.

Documentation

• CLI reference
• Resource reference
• Production hardening guide
• Examples catalog

Examples

All examples live under example/ and include focused scenarios such as:

• minimal app bootstrap
• conditionals and deploy context overrides
• custom Lambda layers
• global and local env vars (with .env file support) and plugins
• DynamoDB TTL (plain + Prismarine)
• Prismarine TypedDict and Pydantic modelling
• OpenSearch Serverless + DynamoDB streams
• Kinesis with multiple S3 destinations

See the full index: example/README.md.

Development

git clone https://github.com/adsight-app/easysam.git
cd easysam
uv sync
source .venv/bin/activate

Changelog

See CHANGELOG.md.

Support

If you hit an issue:

1. Search existing issues
2. Open a new issue with a reproducible example

License

MIT. See LICENSE.