samstacks

samstacks

Declarative infrastructure orchestration for AWS SAM deployments.

Deploy multi-stack AWS SAM applications using YAML pipelines with GitHub Actions-style syntax and automatic dependency resolution.

[!WARNING] Alpha Software Notice: samstacks is currently in alpha development. While functional and actively used, the API and configuration format may change between versions. We welcome feedback, bug reports, and contributions as we work toward a stable release.

Why samstacks?

Managing multiple related AWS SAM stacks can be complex when you need to:

• Deploy stacks in the correct order based on dependencies
• Pass outputs from one stack as parameters to another
• Manage environment-specific configurations
• Coordinate deployments across teams

samstacks solves this by letting you define your entire multi-stack deployment as a single YAML pipeline.

Quick Start

1. Install and run immediately:

uvx samstacks deploy pipeline.yml

No installation required with uvx!

2. Create a pipeline manifest:

# pipeline.yml
pipeline_name: E-commerce Platform
pipeline_description: Backend API with user authentication

stacks:
  - id: auth-service
    dir: ./services/auth
    
  - id: product-api
    dir: ./services/products
    params:
      AuthServiceUrl: ${{ stacks.auth-service.outputs.ServiceUrl }}
      DatabaseUrl: ${{ env.DATABASE_URL }}

3. Deploy your infrastructure:

uvx samstacks deploy pipeline.yml

samstacks automatically:

• ✅ Analyzes dependencies between stacks
• ✅ Deploys auth-service first, then product-api
• ✅ Passes the auth service URL to the product API
• ✅ Provides detailed deployment reporting

Key Features

• Declarative pipeline configuration - Define deployment sequences using YAML manifests
• GitHub Actions compatibility - Leverage familiar ${{ env.VAR }} syntax and expressions
• Intelligent dependency resolution - Automatic stack ordering based on output dependencies
• Multi-environment support - Environment-specific parameters and conditional deployment
• Comprehensive validation - Catch configuration errors before deployment
• Native AWS SAM integration - Works with existing SAM templates and configurations

Installation Options

Recommended - Run without installing:

uvx samstacks --help
uvx samstacks deploy pipeline.yml

Traditional installation:

pip install samstacks
samstacks --help

Common Use Cases

Cross-Stack Dependencies

stacks:
  - id: vpc-stack
    dir: ./infrastructure/vpc
    
  - id: database-stack  
    dir: ./infrastructure/database
    params:
      VpcId: ${{ stacks.vpc-stack.outputs.VpcId }}
      SubnetIds: ${{ stacks.vpc-stack.outputs.PrivateSubnetIds }}
      
  - id: api-stack
    dir: ./application/api
    params:
      DatabaseUrl: ${{ stacks.database-stack.outputs.ConnectionString }}

Environment-Specific Deployment

pipeline_settings:
  stack_name_prefix: ${{ env.ENVIRONMENT }}-myapp
  inputs:
    environment:
      type: string
      default: dev

stacks:
  - id: app-stack
    dir: ./app
    if: ${{ inputs.environment != 'local' }}
    params:
      Environment: ${{ inputs.environment }}
      InstanceType: ${{ inputs.environment == 'prod' && 't3.large' || 't3.micro' }}

CLI Commands

Deploy Pipeline

samstacks deploy pipeline.yml

Validate Configuration

samstacks validate pipeline.yml

Delete All Stacks

samstacks delete pipeline.yml

Bootstrap Existing Project

samstacks bootstrap ./my-sam-project

Prerequisites

• Python 3.8+ - Check with python --version
• AWS CLI - Configured with appropriate permissions (aws sts get-caller-identity)
• SAM CLI - For template validation and deployment (sam --version)

Real-World Example

Check out our complete example showcasing:

• S3 bucket notifications to SQS
• Lambda processing with dependencies
• Cross-stack parameter passing
• Conditional deployment logic
• Post-deployment automation

git clone https://github.com/dev7a/samstacks.git
cd samstacks
uvx samstacks deploy examples/pipeline.yml

Documentation

📖 Complete Documentation

Our comprehensive documentation includes:

• Quickstart Guide - Deploy your first pipeline in 5 minutes
• Manifest Reference - Complete configuration guide with examples
• CLI Reference - All command-line options and usage
• Examples - Real-world pipeline configurations
• FAQ - Common questions and troubleshooting

Contributing

Contributions are welcome! Please see our Contributing Guidelines for details.

License

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