easysam 1.9.0

Opinionated Modular Cloud Deployment Tool (EasySAM)

EasySAM - Opinionated Modular Cloud Deployment Tool

EasySAM is a simple, opinionated tool for deploying cloud resources with a focus on simplicity and modularity. It provides a streamlined way to define and deploy AWS resources using YAML configuration files, making cloud infrastructure management more accessible and maintainable.

Features

• Simple YAML-based resource definitions
• Modular architecture with import support
• Comprehensive AWS resource support:
  • Lambda functions
  • DynamoDB tables with stream support
  • S3 buckets
  • SQS queues
  • Kinesis streams
  • API Gateway integrations
  • MQTT/IoT Core with custom authorizers
• Event-driven architecture:
  • DynamoDB Streams for table change notifications
  • SQS polling
  • Kinesis stream processing
• Easy initialization of new projects

Installation

Quick Start (using uv)

1. Initialize a new project with uv:

uv init
uv add --dev pip
uv add --dev easysam

2. Initialize EasySAM in the current directory:

uv run easysam init

Or with Prismarine support:

uv run easysam init --prismarine

3. Make sure that AWS credentials are configured. The recommended way is to use a named profile and use the --aws-profile option.

4. Deploy your application:

uv run easysam deploy --tag my-tag=my-value --environment my-environment-name .

For more options, use the --help flag:

uv run easysam --help

Prerequisites

• uv 0.5 or higher
• AWS Credentials Configured

Resource Definitions

The entry point for all cloud resources definitions in the resources.yaml file. See example applications for how applications are structures.

Table Definitions

tables:
  - name: String (e.g., Items)
    attributes:
      - name: String (e.g., ItemID)
        type: String (e.g., S), dynamodb type
        hash: Boolean Optional (e.g., true), means Partition Key
        range: Boolean Optional (e.g., true) means Sort Key
    indices:
      - name: String
        attributes:
          - name: String
            type: String
            hash: Boolean Optional
            range: Boolean Optional
    trigger: String or Object - lambda function to trigger on table changes
      # Simple form (just function name, uses defaults):
      # trigger: my-lambda
      # Advanced form (with options):
      # trigger:
      #   function: my-lambda
      #   viewtype: new-and-old  # Optional: keys-only, new, old, new-and-old (default: new-and-old)
      #   batchsize: 10          # Optional: number of records per batch
      #   batchwindow: 5         # Optional: seconds to wait for batch
      #   startingposition: latest  # Optional: trim-horizon, latest (default: latest)

Bucket Definitions

buckets:
  - name: String (e.g., my-bucket)
    public Boolean Optional (e.g., true), means Public read policy

Queue Definitions

queues:
  - name: String (e.g., my-queue)

Stream Definitions

streams:
  - name: String (e.g., my-stream)

Lambda Definition

  - name: String (e.g., my-lambda)
    uri: String (i.e., local path to the source)
    functionurl: Boolean or Object  # Optional: Enable Lambda Function URL
      # Simple form:
      # functionurl: true
      # Advanced form:
      # functionurl:
      #   auth_type: NONE  # Optional: NONE (default) or AWS_IAM
      #   invoke_mode: BUFFERED  # Optional: BUFFERED (default) or RESPONSE_STREAM
      #   cors:
      #     allow_origins: ["*"]
      #     allow_methods: ["GET", "POST"]
    tables:
      - String (e.g., Items)
    polls:
      - String (e.g., my-stream) - incoming stream's name
    buckets:
      - String (e.g., my-bucket)
    send:
      - String (e.g., my-queue) - outgoing queue's name
    services:
      - comprehend  # Grants ComprehendBasicAccessPolicy
      - bedrock     # Grants bedrock:InvokeModel permission
      - mqtt        # Grants iot:Publish and iot:DescribeEndpoint permissions

MQTT Definition

mqtt:
  authorizer:
    function: String  # Lambda function name for custom IoT authorizer
  topics:  # Optional - only needed if not using authorizer-returned policies
    - String  # Topic patterns for client subscribe/receive (e.g., "channels/*")

The MQTT configuration provisions:

• An IoT Core custom authorizer linked to the specified Lambda function
• Lambda permissions for IoT to invoke the authorizer
• (Optional) An IoT client policy if topics is specified - typically not needed since custom authorizers return their own policy documents

Lambda functions that need to publish to IoT topics should include mqtt in their services list.

API Gateway Definition

Lambda Function Integration

  path: # (e.g., /my-lambda)
    function: String # (e.g., my-lambda)
    authorizer: String # (e.g., my-authorizer)
    greedy: Boolean # (e.g., false)

Direct DynamoDB Integration

  path: # (e.g., /my-lambda)
    integration: dynamo
    method: String # (e.g., get)
    parameters: [String] # (e.g., [channel])
    role: GatewayDynamoRole
    action: String # (e.g., GetItem)
    requestTemplate: VTL Template 
    responseTemplateFile: VTL File Path

Direct SQS Integration

  path: # (e.g., /my-lambda)
    integration: sqs
    method: String # (e.g., post)
    role: GatewaySQSRole
    queue: String # (e.g., my-queue)
    requestTemplate: String # VTL Template
    responseTemplateFile: String # VTL File Path
    authorizer: String # (e.g., my-authorizer)

Import

import:
  - <directory>

The import directive searches recursively for easysam.yaml files (local definitions) in the specified directory and merges them into the current template.

Local Lambda Definition

lambda:
  name: <name>
  resources:
    tables:
      - <table>
    buckets:
      - <bucket>
    send:
      - <queue>
    polls:
      - <stream>
  functionurl: <boolean|object>
  integration:
    path: <path>
    open: <boolean>
    greedy: <boolean>
    authorizer: <authorizer-lambda-name>

Locally-defined lambda URI is set to the path of the easysam.yaml file.

Local Import

import:
  - <file>

Prismarine Support

prismarine:
  default-base: <base-path>
  access-module: <access-module-path>
  extra-imports:
    - <path.to.module:ClassName>
  modelling: <typed-dict|pydantic>  # Optional (default: typed-dict)
  tables:
    - package: <package-to-import>
      base: <optional-base-path>

For more information, see Prismarine README.

Set modelling: pydantic to generate Prisma clients backed by Pydantic models (see example/prismapydantic). Omit or set modelling: typed-dict to generate the default TypedDict-based clients.

Conditional Resources

Conditional resources are defined using the !Conditional tag.

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

Negation

The ~ prefix negates the condition.

? !Conditional
  key: my-bucket
  environment: ~prod
  region: ~eu-west-2

Deployment Context File

The deployment context file is used to further control resources, especially in CI. This version has the following features:

• override the resources.yaml file with the values in CI with <path>: <value> pairs.

overrides:
  buckets/my-bucket/public: true

Use the --context-file option to specify the deploy context file.

easysam deploy <app-directory> --environment <aws-environment-name> --context-file deploy-context.yaml

The deploy context file is a YAML file that contains the overrides.

Development

Setting up the development environment

1. Clone the repository:

git clone https://github.com/scartill/easysam.git
cd easysam

2. Install development dependencies and activate the virtual environment:

uv sync
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

Examples

See example folder for examples:

• myapp- a simple application with a lambda function and a table.
• prismarine- a simple application with a lambda function and a table, using Prismarine.
• appwitherrors- an application with some errors in the resources.yaml file, to test the error handling.
• conditionals- an application with conditional resources.
• aoss- an application with Amazon OpenSearch Serverless and DynamoDB Streams integration.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

If you encounter any issues or have questions, please:

1. Search existing issues
2. Create a new issue if needed

Changelog

See CHANGELOG.md for a list of changes between versions.