easysam 1.5.1

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
• Event-driven architecture:
  • DynamoDB Streams for table change notifications
  • SQS polling
  • Kinesis stream processing
• Easy initialization of new projects

Installation

pip install easysam

Quick Start

1. Initialize a new application:

easysam init my-app

2. Deploy your application:

easysam deploy --tag my-tag=my-value --environment my-environment-name my-app

Please note that at least one tag is required.

For more options, use the --help flag:

easysam --help

Windows

On Windows, it may be necessary to run the deploy command with the -sam-tool sam.cmd option.

Prerequisites

• Python 3.12 or higher with pip on PATH
• uv 0.5 or higher
• AWS SAM CLI 1.138 or higher on PATH
• AWS Credentials Configured

Usage

First, initialize a new application. This command creates a new directory with the given name and generates the necessary files for a single lambda function and table. This version only supports AWS as a backend, and Python as a language.

easysam init <app-name>

Deploy the application:

easysam deploy <app-directory> <aws-environment-name>

For more options, use the --help flag:

easysam --help

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)
    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

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>
  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>
  tables:
    - package: <package-to-import>
      base: <optional-base-path>

For more information, see Prismarine README.

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/adsight-app/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.