# samstacks > A pipeline orchestration tool for AWS SAM stacks with advanced templating and dependency management ## About This documentation covers samstacks, a tool that enables you to deploy and manage pipelines of AWS SAM (Serverless Application Model) stacks with advanced templating, cross-stack output referencing, and dependency management. ## Documentation Index ### Main Documentation - **The what and the why** (https://dev7a.github.io/samstacks/docs/introduction/) The What and the Why Modern cloud applications are increasingly built from a collection of interconnected, modular services rather than large, monolithic systems. This architectural style—often inspired by microservices—offers significant advantages: teams can develop, deploy, and scale their … - **Installation** (https://dev7a.github.io/samstacks/docs/installation/) There are several ways to install and use samstacks. Choose the method that works best for your workflow. Quick Run (Recommended) The fastest way to get started is with uvx, which runs samstacks without installing: # Check if samstacks is working uvx samstacks --help # Deploy a pipeline directly uvx … - **Quickstart** (https://dev7a.github.io/samstacks/docs/quickstart/) Deploy your first multi-stack pipeline with samstacks in under 5 minutes. Create Your Pipeline Create a manifest file pipeline.yml: pipeline.ymlpipeline_name: My SAM Application Deployment pipeline_description: Deploys the backend and frontend for My SAM Application. pipeline_settings: … - **Examples** (https://dev7a.github.io/samstacks/docs/examples/) Real-world examples to help you get started with samstacks pipelines. Complete Application Pipeline The examples/ directory contains a comprehensive pipeline demonstrating all samstacks features including security-focused output masking: Features Demonstrated S3 bucket notifications to SQS - … - **Output Masking** (https://dev7a.github.io/samstacks/docs/security-masking/) Protect sensitive information in deployment outputs, reports, and logs with comprehensive data masking. Overview The output masking feature automatically identifies and masks sensitive data in all samstacks outputs, including console displays, deployment reports, pipeline summaries, and template … - **External Configuration** (https://dev7a.github.io/samstacks/docs/external-configs/) External ConfigurationThe external configuration feature allows samstacks to generate standalone SAM configuration files that work independently with the SAM CLI. This enables powerful multi-environment workflows, GitOps practices, and direct team collaboration while maintaining samstacks’ … - **Manifest Reference** (https://dev7a.github.io/samstacks/docs/manifest-reference/) Complete reference for pipeline manifest configuration. Pipeline Metadata pipeline.ymlpipeline_name: My SAM Application Deployment pipeline_description: Description of the pipeline summary: |- Optional post-deployment summary shown in console Pipeline Settings Configure global settings that apply to … - **FAQ** (https://dev7a.github.io/samstacks/docs/faq/) Frequently asked questions about samstacks. General What is samstacks? samstacks is a YAML-driven pipeline tool for deploying AWS SAM stacks. It allows you to define a sequence of stacks in a single manifest using a GitHub Actions-style syntax, with automatic dependency resolution and parameter … ### CLI Reference - **Validate** (https://dev7a.github.io/samstacks/docs/cli/validate/) samstacks validate <manifest-file> Performs comprehensive validation of the manifest including schema checks, template expressions, input definitions, stack dependencies and file existence. - **Deploy** (https://dev7a.github.io/samstacks/docs/cli/deploy/) samstacks deploy <manifest-file> [OPTIONS] Deploys all stacks defined in the manifest. Options include: --input <name=value> to provide values for pipeline inputs --auto-delete-failed to … - **Delete** (https://dev7a.github.io/samstacks/docs/cli/delete/) samstacks delete <manifest-file> [OPTIONS] Deletes all stacks defined in the manifest in reverse dependency order. Useful options: --input <name=value> to provide pipeline input values … - **Bootstrap** (https://dev7a.github.io/samstacks/docs/cli/bootstrap/) samstacks bootstrap [PATH_TO_SCAN] [OPTIONS] Scans a directory for existing SAM projects and generates an initial pipeline.yml file. Useful options include --output-file to name the generated file … --- ## Complete Documentation # Validate **Source:** https://dev7a.github.io/samstacks/docs/cli/validate/ **Last Updated:** 0001-01-01 samstacks validate Performs comprehensive validation of the manifest including schema checks, template expressions, input definitions, stack dependencies and file existence. # Deploy **Source:** https://dev7a.github.io/samstacks/docs/cli/deploy/ **Last Updated:** 0001-01-01 samstacks deploy [OPTIONS] Deploys all stacks defined in the manifest. Options include: --input to provide values for pipeline inputs --auto-delete-failed to clean up failed stacks and changesets --report-file to save a Markdown summary --debug for verbose logging --quiet to suppress output Deployment reports include a console summary and optional Markdown file. # Delete **Source:** https://dev7a.github.io/samstacks/docs/cli/delete/ **Last Updated:** 0001-01-01 samstacks delete [OPTIONS] Deletes all stacks defined in the manifest in reverse dependency order. Useful options: --input to provide pipeline input values for multi-environment deployments --no-prompts to skip confirmation --dry-run to preview deletions Multi-Environment Support The delete command supports the same --input parameter as deploy for multi-environment pipelines: # Delete dev environment samstacks delete pipeline.yml --input environment=dev # Delete production environment samstacks delete pipeline.yml --input environment=prod For pipelines using external configurations, the delete command will: Resolve template expressions in config paths based on input values Use the appropriate external config files with sam delete --config-file Fall back to local samconfig.yaml files when external configs aren’t found # Bootstrap **Source:** https://dev7a.github.io/samstacks/docs/cli/bootstrap/ **Last Updated:** 0001-01-01 samstacks bootstrap [PATH_TO_SCAN] [OPTIONS] Scans a directory for existing SAM projects and generates an initial pipeline.yml file. Useful options include --output-file to name the generated file and --overwrite to replace an existing file. # The what and the why **Source:** https://dev7a.github.io/samstacks/docs/introduction/ **Last Updated:** 0001-01-01 The What and the Why Modern cloud applications are increasingly built from a collection of interconnected, modular services rather than large, monolithic systems. This architectural style—often inspired by microservices—offers significant advantages: teams can develop, deploy, and scale their components independently, leading to faster innovation, improved resilience, and better resource utilization. Each module, or “stack” in AWS SAM terminology, can focus on a specific business capability, making the overall system easier to understand, maintain, and evolve. However, managing a distributed system composed of many small, independent stacks introduces its own set of challenges. How do you ensure that stacks are deployed in the correct order, especially when they depend on each other’s outputs? How do you manage configurations consistently across multiple environments? How do you get a clear overview of your entire application’s deployment status? This is where samstacks comes in. Note samstacks is a declarative infrastructure orchestration tool specifically designed for AWS SAM (Serverless Application Model) deployments. It empowers you to define and manage complex, multi-stack serverless applications with the simplicity and power of a GitHub Actions-like workflow. Instead of manually coordinating deployments or wrestling with complex scripts, you can describe your entire application pipeline—including stack dependencies, parameters, and post-deployment actions—in a single, easy-to-understand YAML manifest. A fundamental design principle of samstacks is that each stack should be able to be deployed independently. This is a key difference from other IaC tools that require you to define a single, monolithic template that includes all the resources for an entire application. Run the pipeline as a whole, commit the changes, and each stack can be deployed independently, with just sam build && sam deploy. Embrace Modularity with Confidence With samstacks, you can fully embrace the benefits of modular architecture for your AWS SAM projects: Clear Dependency Management: Explicitly define dependencies between your stacks. Samstacks automatically determines the correct deployment order, ensuring that producer stacks are deployed before their consumers. Simplified Orchestration: Define your entire deployment pipeline in one place. No more juggling multiple sam deploy commands or custom scripts. Reusable Stacks: Design your SAM templates as reusable building blocks that can be composed into different application pipelines. Consistent Environments: Easily manage configurations for different environments (dev, staging, prod) using templated parameters and inputs. Improved Visibility: Gain a clear overview of your application’s structure and deployment status. Where Samstacks Fits In The landscape of Infrastructure as Code (IaC) tools is rich, with powerful and comprehensive solutions like AWS Cloud Development Kit (CDK) and HashiCorp Terraform, or Pulumi, all offering sophisticated ways to manage complex cloud environments. These tools provide extensive capabilities for defining and provisioning a wide array of cloud resources. It’s also true that AWS CloudFormation (and by extension, AWS SAM) offers its own native features for modularity, such as Nested Stacks, Cross-Stack References (Exports/Imports), CloudFormation Modules, and the ability to create Custom Resources and private or public Resource Types. These are powerful primitives for breaking down large templates and reusing common patterns. However, each of these native CloudFormation mechanisms can introduce its own complexities or limitations when used for orchestrating application-level pipelines of multiple, independently-deployable SAM stacks: Nested Stacks: While useful for composing a single, larger logical unit, they can become cumbersome to manage and update, especially with deep nesting or extensive parameter passing. Debugging issues within nested stacks can also be less straightforward. Cross-Stack References (Exports/Imports): The immutability of exported values is a significant constraint. Once an output is exported and consumed, the producing stack cannot easily modify or remove that export, which can hinder iterative development and refactoring. This can lead to a rigid infrastructure that’s difficult to evolve. CloudFormation Modules: These are excellent for encapsulating and reusing common resource configurations within a single CloudFormation template. They help create reusable components at the template level but don’t directly address the orchestration of multiple, distinct stack deployments with interdependencies. Custom Resources & Resource Types: These are powerful for extending CloudFormation’s capabilities to manage new or third-party resources. However, developing, testing, and maintaining custom resources (often involving Lambda functions) adds a significant layer of complexity and is generally overkill for simply managing the deployment flow of standard SAM stacks. Samstacks is not intended to replace these broader IaC solutions or CloudFormation’s native modularity features. Instead, it focuses on a specific, common challenge: orchestrating pipelines of multiple, largely independent AWS SAM stacks. If your team is already leveraging AWS SAM for its streamlined approach to defining serverless applications, samstacks provides a lightweight, intuitive higher-level orchestration layer. Think of samstacks as a focused orchestrator that complements your SAM development workflow by simplifying the flow and data passing between your SAM stacks. For instance, samstacks’ ${{ stacks..outputs. }} templating offers a more flexible way to consume outputs during pipeline execution compared to the compile-time rigidity of CloudFormation exports, especially easing development and refactoring cycles. It allows each SAM stack to remain a more self-contained, independently deployable unit, while samstacks manages their assembly into a cohesive application. It’s ideal when: You primarily use AWS SAM for defining your serverless components. You need a simple, declarative way to manage dependencies and deployment order for multiple SAM stacks, avoiding the operational complexities of deeply nested stacks or the inflexibility of immutable exports for dynamic application composition. You prefer a GitHub Actions-like syntax for pipeline definition without wanting to adopt a more comprehensive IaC tool for this specific orchestration task. You want to maintain the simplicity of SAM while gaining better control over multi-stack deployments. Samstacks helps bridge the gap between individual SAM stack deployments and a fully orchestrated application, keeping the focus on SAM’s strengths for serverless development. # Installation **Source:** https://dev7a.github.io/samstacks/docs/installation/ **Last Updated:** 0001-01-01 There are several ways to install and use samstacks. Choose the method that works best for your workflow. Quick Run (Recommended) The fastest way to get started is with uvx, which runs samstacks without installing: # Check if samstacks is working uvx samstacks --help # Deploy a pipeline directly uvx samstacks deploy pipeline.yml Tip No setup required! uvx automatically manages Python environments and dependencies. Local Installation For regular use, install samstacks in a virtual environment: With uv (Recommended) # Create virtual environment uv venv # Activate and install source .venv/bin/activate # On Windows: .venv\Scripts\activate uv pip install samstacks # Verify installation samstacks --help With pip # Create virtual environment python -m venv .venv # Activate and install source .venv/bin/activate # On Windows: .venv\Scripts\activate pip install samstacks # Verify installation samstacks --help Prerequisites Python 3.12+ - Check with python --version AWS CLI - Configured with appropriate permissions SAM CLI - For template validation and deployment Next Steps Quickstart Guide - Deploy your first pipeline Examples - See real-world configurations # Quickstart **Source:** https://dev7a.github.io/samstacks/docs/quickstart/ **Last Updated:** 0001-01-01 Deploy your first multi-stack pipeline with samstacks in under 5 minutes. Create Your Pipeline Create a manifest file pipeline.yml: pipeline.ymlpipeline_name: My SAM Application Deployment pipeline_description: Deploys the backend and frontend for My SAM Application. pipeline_settings: default_sam_config: version: 0.1 default: deploy: parameters: capabilities: CAPABILITY_IAM confirm_changeset: false stacks: - id: backend dir: my_sam_app/backend/ params: TableName: ${{ env.TABLE_NAME || 'MyTable' }} - id: frontend dir: my_sam_app/frontend/ params: ApiEndpoint: ${{ stacks.backend.outputs.ApiUrl }} Deploy Your Pipeline # Using uvx (recommended) uvx samstacks deploy pipeline.yml # Or if installed globally samstacks deploy pipeline.yml Execution Flow samstacks will: Dependency analysis - Construct deployment dependency graph Backend stack deployment - Provision API and database infrastructure Frontend stack deployment - Resolve backend outputs as input parameters Status reporting - Display deployment results and stack outputs Next Steps Installation Guide - Install samstacks locally Manifest Reference - Complete configuration options Examples - Real-world use cases # Examples **Source:** https://dev7a.github.io/samstacks/docs/examples/ **Last Updated:** 0001-01-01 Real-world examples to help you get started with samstacks pipelines. Complete Application Pipeline The examples/ directory contains a comprehensive pipeline demonstrating all samstacks features including security-focused output masking: Features Demonstrated S3 bucket notifications to SQS - Event-driven architecture Lambda processing - Serverless file processing Stack output dependencies - Dynamic parameter passing Centralized SAM configuration - Shared deployment settings Conditional deployment - Environment-based logic Post-deployment scripts - Custom automation Summary reporting - Deployment insights Expression evaluation - Mathematical and logical operations Security-focused masking - Protect sensitive data in outputs Pipeline Structure examples/pipeline.ymlpipeline_name: File Processing System pipeline_description: S3 → SQS → Lambda processing pipeline stacks: - id: storage dir: stacks/storage/ - id: processor dir: stacks/processor/ params: BucketName: ${{ stacks.storage.outputs.BucketName }} QueueUrl: ${{ stacks.storage.outputs.QueueUrl }} Try the Examples Basic Multi-Stack Pipeline # Clone and deploy the basic example git clone https://github.com/dev7a/samstacks.git cd samstacks/examples # Deploy the basic pipeline uvx samstacks deploy pipeline.yml Multi-Environment External Configuration # Deploy to different environments uvx samstacks deploy multi-pipeline.yml --input environment=dev uvx samstacks deploy multi-pipeline.yml --input environment=prod # Or use SAM CLI directly with generated configs cd configs/dev/processor && sam deploy cd configs/prod/processor && sam deploy Common Patterns External Configuration for Multi-Environment external-config.ymlpipeline_settings: inputs: environment: type: string default: dev stacks: - id: api dir: stacks/api/ config: configs/${{ inputs.environment }}/api/ params: Environment: ${{ inputs.environment }} LogLevel: ${{ inputs.environment == 'prod' && 'WARN' || 'DEBUG' }} InstanceType: ${{ inputs.environment == 'prod' && 't3.large' || 't3.micro' }} Traditional Multi-Environment Deployment multi-env.ymlstacks: - id: app dir: ./app if: ${{ env.ENVIRONMENT == 'production' }} params: InstanceType: t3.large - id: app-dev dir: ./app if: ${{ env.ENVIRONMENT == 'development' }} params: InstanceType: t3.micro Cross-Stack References cross-stack.ymlstacks: - id: network dir: ./infrastructure/network - id: database dir: ./infrastructure/database params: VpcId: ${{ stacks.network.outputs.VpcId }} SubnetIds: ${{ stacks.network.outputs.PrivateSubnetIds }} Secure Deployment with Masking secure-pipeline.ymlpipeline_settings: output_masking: enabled: true categories: account_ids: true api_endpoints: true database_endpoints: true stacks: - id: api dir: ./api # Account IDs, endpoints automatically masked in outputs Next Steps Manifest Reference - Complete configuration guide CLI Reference - Command-line options # Output Masking **Source:** https://dev7a.github.io/samstacks/docs/security-masking/ **Last Updated:** 0001-01-01 Protect sensitive information in deployment outputs, reports, and logs with comprehensive data masking. Overview The output masking feature automatically identifies and masks sensitive data in all samstacks outputs, including console displays, deployment reports, pipeline summaries, and template expressions. This helps protect sensitive information when sharing deployment artifacts, logs, or reports. Quick Start Enable comprehensive masking with minimal configuration: pipeline.ymlpipeline_settings: output_masking: enabled: true # Enables ALL categories by default stacks: - id: my-stack dir: ./my-stack Or enable specific categories only: pipeline.ymlpipeline_settings: output_masking: enabled: true categories: account_ids: true # Only enable account ID masking api_endpoints: true # Only enable API endpoint masking stacks: - id: my-stack dir: ./my-stack Result: # Before masking FunctionArn: arn:aws:lambda:us-west-2:123456789012:function:my-function # After masking FunctionArn: arn:aws:lambda:us-west-2:************:function:my-function Configuration Basic Configuration Simple (enables all categories by default): pipeline.ymlpipeline_settings: output_masking: enabled: true # Enables ALL categories automatically Explicit (same effect, but shows all available options): pipeline.ymlpipeline_settings: output_masking: enabled: true # Master switch for all masking categories: account_ids: true # AWS account IDs (12-digit numbers) api_endpoints: true # API Gateway and Lambda Function URLs database_endpoints: true # RDS, ElastiCache, DocumentDB endpoints load_balancer_dns: true # ALB, NLB, CLB DNS names cloudfront_domains: true # CloudFront distribution domains s3_bucket_domains: true # S3 website and transfer endpoints ip_addresses: true # IPv4 and IPv6 addresses Advanced Configuration with Custom Patterns pipeline.ymlpipeline_settings: output_masking: enabled: true categories: account_ids: true api_endpoints: true custom_patterns: - pattern: "secret-[a-zA-Z0-9]+" replacement: "secret-***" description: "Mask secret tokens" - pattern: "key-[0-9]+" replacement: "key-***" description: "Mask API keys" Masking Categories Account IDs Masks 12-digit AWS account IDs in various contexts: Patterns detected: ARNs: arn:aws:service:region:123456789012:resource SQS URLs: https://sqs.region.amazonaws.com/123456789012/queue S3 bucket names with account IDs: mybucket-123456789012 Examples: # Input FunctionArn: arn:aws:lambda:us-west-2:123456789012:function:processor QueueUrl: https://sqs.us-west-2.amazonaws.com/123456789012/notifications # Output FunctionArn: arn:aws:lambda:us-west-2:************:function:processor QueueUrl: https://sqs.us-west-2.amazonaws.com/************/notifications API Endpoints Masks API Gateway and Lambda Function URLs: Patterns detected: API Gateway: https://{api-id}.execute-api.region.amazonaws.com Lambda Function URLs: https://{function-url}.lambda-url.region.on.aws Custom domains: https://{subdomain}.{domain}.com/api Examples: # Input ApiUrl: https://abc123def.execute-api.us-west-2.amazonaws.com/prod FunctionUrl: https://xyz789ghi.lambda-url.us-east-1.on.aws/ # Output ApiUrl: https://******.execute-api.us-west-2.amazonaws.com/prod FunctionUrl: https://******.lambda-url.us-east-1.on.aws/ Database Endpoints Masks database connection endpoints: Patterns detected: RDS: {instance}.{random}.region.rds.amazonaws.com ElastiCache: {cluster}.{random}.cache.amazonaws.com DocumentDB: {cluster}.{random}.docdb.amazonaws.com Neptune: {cluster}.{random}.neptune.amazonaws.com Examples: # Input DatabaseEndpoint: myapp.abc123.us-west-2.rds.amazonaws.com CacheEndpoint: redis.def456.cache.amazonaws.com # Output DatabaseEndpoint: myapp.******.us-west-2.rds.amazonaws.com CacheEndpoint: redis.******.cache.amazonaws.com Load Balancer DNS Masks Elastic Load Balancer DNS names: Patterns detected: Application Load Balancer: {name}-{random}.region.elb.amazonaws.com Network Load Balancer: {name}-{random}.elb.region.amazonaws.com Classic Load Balancer: {name}-{random}.region.elb.amazonaws.com Examples: # Input LoadBalancerDns: my-app-alb-1234567890.us-west-2.elb.amazonaws.com # Output LoadBalancerDns: my-app-alb-*********.us-west-2.elb.amazonaws.com CloudFront Domains Masks CloudFront distribution domains: Examples: # Input CdnDomain: d1a2b3c4d5e6f.cloudfront.net # Output CdnDomain: d************.cloudfront.net S3 Bucket Domains Masks S3 website and transfer acceleration endpoints: Patterns detected: Website endpoints: {bucket}.s3-website-region.amazonaws.com Transfer acceleration: {bucket}.s3-accelerate.amazonaws.com Dual-stack: {bucket}.s3.dualstack.region.amazonaws.com Examples: # Input WebsiteUrl: mybucket.s3-website-us-west-2.amazonaws.com AccelerateUrl: mybucket.s3-accelerate.amazonaws.com # Output WebsiteUrl: ********.s3-website-us-west-2.amazonaws.com AccelerateUrl: ********.s3-accelerate.amazonaws.com IP Addresses Masks IPv4 and IPv6 addresses: Examples: # Input ServerIp: 192.168.1.100 ServerIpv6: 2001:db8::1 # Output ServerIp: ***.***.***.*** ServerIpv6: ****:***::* Custom Patterns Define application-specific masking patterns using regular expressions: pipeline.ymlpipeline_settings: output_masking: enabled: true custom_patterns: # Mask secret tokens - pattern: "secret-[a-zA-Z0-9]+" replacement: "secret-***" description: "Application secret tokens" # Mask API keys - pattern: "ak-[0-9]+" replacement: "ak-***" description: "API access keys" # Mask database passwords in connection strings - pattern: "password=[^;\\s]+" replacement: "password=***" description: "Database passwords" # Mask JWT tokens - pattern: "eyJ[A-Za-z0-9-_=]+\\.[A-Za-z0-9-_=]+\\.?[A-Za-z0-9-_.+/=]*" replacement: "eyJ***" description: "JWT tokens" Custom pattern rules: Use standard regex syntax Escape special characters appropriately Test patterns thoroughly before deployment Keep replacements consistent for the same data type Masking Scope Output masking applies to: Console Output Stack parameter displays during deployment Stack output displays after deployment Pipeline summary rendering Error messages and logs Deployment Reports Console summary reports (samstacks deploy) Markdown file reports (--report-file) Stack parameter tables Stack output tables Pipeline Summaries Post-deployment summary content Template expression evaluation in summaries Markdown rendering of summary content Template Expressions All template expressions are processed through masking when enabled: ${{ stacks.my-stack.outputs.SensitiveData }} Pipeline summary content containing sensitive data Environment variable resolution Best Practices Security Guidelines Enable comprehensive masking for production pipelines: output_masking: enabled: true # This alone enables all security categories Use custom patterns for application-specific secrets: custom_patterns: - pattern: "your-app-secret-[a-zA-Z0-9]+" replacement: "your-app-secret-***" Validate patterns in development before production deployment Document masking rules in your team’s deployment procedures Development Workflow Development: Start with masking disabled for easier debugging Staging: Enable relevant masking categories to test patterns Production: Enable comprehensive masking for security # Development pipeline_settings: output_masking: enabled: false # Staging pipeline_settings: output_masking: enabled: true categories: account_ids: true # Production pipeline_settings: output_masking: enabled: true categories: account_ids: true api_endpoints: true database_endpoints: true load_balancer_dns: true cloudfront_domains: true s3_bucket_domains: true ip_addresses: true CI/CD Integration For CI/CD pipelines, enable masking to protect logs and artifacts: # GitHub Actions example - name: Deploy with masked outputs run: | uvx samstacks deploy pipeline.yml --report-file deployment-report.md - name: Upload masked report uses: actions/upload-artifact@v3 with: name: deployment-report path: deployment-report.md Performance Considerations Masking adds minimal overhead to deployment Custom patterns are evaluated in order - place more specific patterns first Complex regex patterns may impact performance with large outputs Consider the number of custom patterns (recommended: < 10) Troubleshooting Common Issues Pattern not matching: # Problem: Pattern too specific pattern: "secret-123456" # Solution: Use broader pattern pattern: "secret-[0-9]+" Unexpected masking: # Problem: Pattern too broad pattern: "[0-9]+" # Masks all numbers # Solution: Be more specific pattern: "key-[0-9]+" # Only masks key- prefixed numbers Masking not applied: # Problem: Master switch disabled output_masking: enabled: false # Must be true categories: account_ids: true Testing Patterns Use a test pipeline to validate custom patterns: test-masking.ymlpipeline_name: Masking Test pipeline_settings: output_masking: enabled: true custom_patterns: - pattern: "test-[a-z]+" replacement: "test-***" stacks: - id: test-stack dir: ./test-stack params: TestValue: "test-secret-data" Examples Complete E-commerce Application ecommerce-pipeline.ymlpipeline_name: E-commerce Platform pipeline_description: Secure deployment with comprehensive masking pipeline_settings: output_masking: enabled: true categories: account_ids: true api_endpoints: true database_endpoints: true load_balancer_dns: true ip_addresses: true custom_patterns: - pattern: "stripe_[a-zA-Z0-9_]+" replacement: "stripe_***" description: "Stripe API keys" - pattern: "jwt_[A-Za-z0-9-_=]+\\.[A-Za-z0-9-_=]+\\.?[A-Za-z0-9-_.+/=]*" replacement: "jwt_***" description: "JWT tokens" stacks: - id: database dir: ./infrastructure/database - id: api dir: ./application/api params: DatabaseUrl: ${{ stacks.database.outputs.ConnectionString }} - id: frontend dir: ./application/frontend params: ApiEndpoint: ${{ stacks.api.outputs.ApiUrl }} summary: | # 🛡️ Secure Deployment Complete Your e-commerce platform has been deployed with comprehensive security masking. ## Key Endpoints - **API**: ${{ stacks.api.outputs.ApiUrl }} - **Database**: ${{ stacks.database.outputs.ConnectionString }} - **Load Balancer**: ${{ stacks.api.outputs.LoadBalancerDns }} All sensitive data above has been automatically masked for security. This configuration ensures that all deployment outputs, reports, and logs protect sensitive information while maintaining useful deployment visibility. # External Configuration **Source:** https://dev7a.github.io/samstacks/docs/external-configs/ **Last Updated:** 0001-01-01 External ConfigurationThe external configuration feature allows samstacks to generate standalone SAM configuration files that work independently with the SAM CLI. This enables powerful multi-environment workflows, GitOps practices, and direct team collaboration while maintaining samstacks’ orchestration benefits. Overview By default, samstacks uses local samconfig.yaml files in each stack directory. External configurations change this behavior by generating SAM config files at specified paths outside the stack directories. Key Benefits Single Source of Truth: One pipeline definition supports multiple environments Standalone Configs: Generated configurations work independently with SAM CLI Clean Repositories: No generated files mixed with source code GitOps Ready: Commit generated configs for reproducible deployments Direct SAM CLI Usage: Skip orchestrator for quick individual stack deployments Team Collaboration: Different teams can use SAM CLI directly Basic Usage Add a config field to any stack definition to enable external configuration: pipeline_name: My Application stacks: - id: api dir: stacks/api/ config: configs/production/api/ # External config directory params: Environment: production When deployed, samstacks will: Generate a complete SAM configuration file at configs/production/api/samconfig.yaml Deploy the stack using the external configuration Create all necessary directories automatically Tip Directory-Based Configs: Using config: configs/production/api/ (ending with /) automatically creates samconfig.yaml in that directory. This prevents conflicts with shared .aws-sam build directories and follows the “one directory, one stack” philosophy. Multi-Environment Deployment The most powerful use case is deploying the same pipeline to multiple environments using template expressions: pipeline_name: Multi-Environment API pipeline_settings: inputs: environment: type: string default: dev stacks: - id: backend-api dir: stacks/api/ config: configs/${{ inputs.environment }}/api/ params: Environment: ${{ inputs.environment }} LogLevel: ${{ inputs.environment == 'prod' && 'WARN' || 'DEBUG' }} InstanceType: ${{ inputs.environment == 'prod' && 't3.large' || 't3.micro' }} - id: database dir: stacks/database/ config: configs/${{ inputs.environment }}/database/ params: Environment: ${{ inputs.environment }} BackupRetentionDays: ${{ inputs.environment == 'prod' && '365' || '7' }} Deploy to Multiple Environments # Deploy to development samstacks deploy pipeline.yml --input environment=dev # Deploy to staging samstacks deploy pipeline.yml --input environment=staging # Deploy to production samstacks deploy pipeline.yml --input environment=prod Delete Environment-Specific Deployments The delete command supports the same multi-environment functionality: # Delete development environment samstacks delete pipeline.yml --input environment=dev # Delete staging environment (with dry-run preview) samstacks delete pipeline.yml --input environment=staging --dry-run # Delete production environment samstacks delete pipeline.yml --input environment=prod For external configurations, the delete command will: Resolve template expressions in config paths based on input values Use the appropriate external config files with sam delete --config-file Fall back to local samconfig.yaml files when external configs aren’t found This creates the following structure: project/ ├── pipeline.yml ├── stacks/ │ ├── api/ │ │ ├── template.yaml │ │ └── src/ │ └── database/ │ └── template.yaml └── configs/ # Generated external configs ├── dev/ │ ├── api/ │ │ └── samconfig.yaml # Dev-specific API config │ └── database/ │ └── samconfig.yaml # Dev-specific DB config ├── staging/ │ ├── api/ │ │ └── samconfig.yaml │ └── database/ │ └── samconfig.yaml └── prod/ ├── api/ │ └── samconfig.yaml └── database/ └── samconfig.yaml Template Path Resolution External SAM configurations automatically include proper template file references using relative paths: Generated Configuration Example When you define: - id: api dir: stacks/api/ config: configs/dev/api/ The generated configs/dev/api/samconfig.yaml contains: version: 0.1 default: global: parameters: beta_features: false build: parameters: template: ../../../stacks/api/template.yaml # Relative path to template deploy: parameters: stack_name: my-app-dev-api region: us-west-2 capabilities: CAPABILITY_IAM parameter_overrides: - Environment=dev - LogLevel=DEBUG template: ../../../stacks/api/template.yaml # Relative path to template The relative paths (../../../stacks/api/template.yaml) are automatically calculated to point from the config file location to the actual CloudFormation template. Config Path Formats samstacks supports two config path formats with built-in validation: Directory-Based (Recommended) # Automatically creates samconfig.yaml in the specified directory config: configs/${{ inputs.environment }}/api/ Benefits: Isolated Build Artifacts: Each config gets its own .aws-sam/ directory Clean SAM CLI Usage: cd configs/dev/api && sam deploy works naturally No File Conflicts: Multiple stacks can’t interfere with each other Follows Best Practices: Maintains “one directory, one stack” philosophy Explicit File Path # Use a specific filename config: configs/${{ inputs.environment }}/api/samconfig.yaml config: shared/environments/dev-api-config.yml Validation Rules samstacks validates config paths to prevent common issues: Ends with /: Directory path → automatically appends samconfig.yaml Ends with .yaml or .yml: File path → used as-is Anything else: Validation error with helpful message # ✅ Valid configurations config: configs/dev/api/ # Directory-based config: configs/dev/api/samconfig.yaml # Explicit file config: environments/dev/api-config.yml # Custom filename # ❌ Invalid configurations config: configs/dev/api # Missing trailing slash or extension config: configs/dev/api/config.json # Wrong file extension Direct SAM CLI Usage Generated external configurations work seamlessly with the SAM CLI: Individual Stack Deployment # Navigate to the config directory and deploy cd configs/dev/api sam deploy # Or specify the config file explicitly sam deploy --config-file configs/dev/api/samconfig.yaml # Build and deploy in sequence cd configs/dev/api sam build && sam deploy Individual Stack Deletion # Navigate to the config directory and delete cd configs/dev/api sam delete --no-prompts # Or specify the config file explicitly sam delete --config-file configs/dev/api/samconfig.yaml --no-prompts Team Workflows Different team members can deploy and delete using their preferred tool: # DevOps team uses samstacks for orchestration samstacks deploy pipeline.yml --input environment=dev samstacks delete pipeline.yml --input environment=dev # Development team uses SAM CLI for quick iterations cd configs/dev/api && sam deploy cd configs/dev/api && sam delete --no-prompts # CI/CD pipeline uses generated configs sam deploy --config-file configs/prod/api/samconfig.yaml sam delete --config-file configs/prod/api/samconfig.yaml --no-prompts Configuration Backup and Safety External configurations include built-in safety features: Automatic Backups When an external config file already exists, samstacks automatically creates a backup: configs/dev/api/ ├── samconfig.yaml # New configuration └── samconfig.yaml.bak # Previous version backup Directory Creation samstacks automatically creates all necessary parent directories: # This works even if configs/ doesn't exist yet config: configs/new-env/new-stack/samconfig.yaml Advanced Use Cases GitOps Workflows Commit generated configurations for reproducible deployments: # Generate configs for all environments samstacks deploy pipeline.yml --input environment=dev samstacks deploy pipeline.yml --input environment=staging samstacks deploy pipeline.yml --input environment=prod # Commit the generated configs git add configs/ git commit -m "Update deployment configurations" git push # Deploy/delete in CI/CD using committed configs sam deploy --config-file configs/prod/api/samconfig.yaml sam delete --config-file configs/prod/api/samconfig.yaml --no-prompts Environment Isolation Keep different environments completely isolated: stacks: - id: api dir: stacks/api/ config: environments/${{ inputs.environment }}/api/ if: ${{ inputs.environment != 'local' }} # Skip for local development Cross-Stack Dependencies External configs work perfectly with cross-stack dependencies: stacks: - id: vpc dir: stacks/vpc/ config: configs/${{ inputs.environment }}/vpc/ - id: app dir: stacks/app/ config: configs/${{ inputs.environment }}/app/ params: VpcId: ${{ stacks.vpc.outputs.VpcId }} # Reference to previous stack Migration from Local Configs Converting existing pipelines to use external configs is straightforward: Before (Local Configs) stacks: - id: api dir: stacks/api/ # Uses stacks/api/samconfig.yaml params: Environment: production After (External Configs) stacks: - id: api dir: stacks/api/ config: configs/production/api/ # External config directory params: Environment: production The functionality remains identical, but the configuration is now generated externally. Best Practices Directory Structure Use consistent, predictable directory structures: configs/ ├── {environment}/ │ ├── {stack-name}/ │ │ └── samconfig.yaml │ └── {another-stack}/ │ └── samconfig.yaml └── {another-environment}/ └── ... Environment Naming Use standard environment names: # Good - Directory-based (recommended) config: configs/${{ inputs.environment }}/api/ # Good - Explicit file path config: configs/${{ inputs.environment }}/api/samconfig.yaml # With validation pipeline_settings: inputs: environment: type: string default: dev allowed_values: [dev, staging, prod] Template Expressions Leverage template expressions for environment-specific behavior: params: LogLevel: ${{ inputs.environment == 'prod' && 'WARN' || 'DEBUG' }} InstanceType: ${{ inputs.environment == 'prod' && 't3.large' || 't3.micro' }} EnableMonitoring: ${{ inputs.environment == 'prod' }} BackupRetentionDays: ${{ inputs.environment == 'prod' && '365' || '7' }} Troubleshooting Template File Not Found If you see “Template file not found” errors: Check relative paths: Ensure the generated config can find the template Verify directory structure: Make sure stack directories exist Review working directory: SAM CLI runs from the config file’s directory Permission Issues If directories cannot be created: Check write permissions for the config path parent directories Avoid system directories like /etc or /usr (blocked for security) Use relative paths for better portability Missing Parameters If CloudFormation validation fails: Check parameter mapping in the pipeline definition Verify template requirements match provided parameters Review cross-stack dependencies are properly defined Examples For complete working examples, see: Multi-Environment Example - Single pipeline supporting multiple environments Generated Configs - Example external configuration outputs Configuration README - Detailed explanation of the example structure # Manifest Reference **Source:** https://dev7a.github.io/samstacks/docs/manifest-reference/ **Last Updated:** 0001-01-01 Complete reference for pipeline manifest configuration. Pipeline Metadata pipeline.ymlpipeline_name: My SAM Application Deployment pipeline_description: Description of the pipeline summary: |- Optional post-deployment summary shown in console Pipeline Settings Configure global settings that apply to all stacks: pipeline.ymlpipeline_settings: stack_name_prefix: myapp- # Prefix for all stack names default_region: us-east-1 # Default AWS region default_sam_config: # Shared SAM configuration version: 0.1 default: deploy: parameters: capabilities: CAPABILITY_IAM confirm_changeset: false output_masking: # Security-focused output masking enabled: true categories: account_ids: true # Mask AWS account IDs api_endpoints: true # Mask API Gateway URLs database_endpoints: true # Mask database connection strings inputs: # Pipeline input parameters environment: type: string default: development Stack Configuration Define your deployment stacks: pipeline.ymlstacks: - id: network # Unique stack identifier dir: infrastructure/network # Directory containing SAM template if: ${{ env.DEPLOY_NETWORK }} # Conditional deployment params: # Stack parameters Environment: ${{ inputs.environment }} run: |- # Post-deployment actions echo "Network deployed successfully" Stack Properties Required Properties Property Type Description id string Unique identifier for the stack dir string Directory containing the SAM template and code Optional Properties Property Type Description name string Human-readable name for the stack description string Description of the stack if string Conditional expression for deployment config string Path for external SAM configuration file generation params object Parameters to pass to the stack run string Commands to run after deployment region string AWS region override for this stack profile string AWS profile override for this stack stack_name_suffix string Stack-specific suffix for naming sam_config_overrides object Stack-specific SAM configuration External Configuration Enable generation of standalone SAM configuration files using the config field: pipeline.ymlstacks: - id: api dir: stacks/api/ config: configs/production/api/ # External config directory params: Environment: production Multi-Environment Example pipeline.ymlpipeline_settings: inputs: environment: type: string default: dev stacks: - id: backend dir: stacks/backend/ config: configs/${{ inputs.environment }}/backend/ params: Environment: ${{ inputs.environment }} LogLevel: ${{ inputs.environment == 'prod' && 'WARN' || 'DEBUG' }} For complete documentation, see External Configuration. Expression Language samstacks supports GitHub Actions-style expressions: Environment Variables params: Environment: ${{ env.ENVIRONMENT || 'development' }} Stack Outputs params: VpcId: ${{ stacks.network.outputs.VpcId }} DatabaseUrl: ${{ stacks.database.outputs.ConnectionString }} Input Parameters params: InstanceType: ${{ inputs.instance_type }} Conditional Logic if: ${{ env.ENVIRONMENT == 'production' }} if: ${{ inputs.deploy_database == 'true' }} Mathematical Operations params: DesiredCapacity: ${{ inputs.base_capacity * 2 }} MaxSize: ${{ inputs.base_capacity + 10 }} Complete Example pipeline.ymlpipeline_name: Multi-Tier Application pipeline_description: Web application with database and API pipeline_settings: stack_name_prefix: myapp- default_region: us-west-2 inputs: environment: type: string default: development stacks: - id: network dir: infrastructure/network params: Environment: ${{ inputs.environment }} - id: database dir: infrastructure/database if: ${{ inputs.environment != 'test' }} params: VpcId: ${{ stacks.network.outputs.VpcId }} SubnetIds: ${{ stacks.network.outputs.PrivateSubnetIds }} - id: api dir: application/api params: DatabaseUrl: ${{ stacks.database.outputs.ConnectionString }} Environment: ${{ inputs.environment }} run: |- echo "API deployed to: ${{ stacks.api.outputs.ApiUrl }}" Security Features Output Masking Protect sensitive information in deployment outputs: pipeline.ymlpipeline_settings: output_masking: enabled: true # Master switch for all masking categories: account_ids: true # AWS account IDs (12-digit numbers) api_endpoints: true # API Gateway and Lambda Function URLs database_endpoints: true # RDS, ElastiCache, DocumentDB endpoints load_balancer_dns: true # ALB, NLB, CLB DNS names cloudfront_domains: true # CloudFront distribution domains s3_bucket_domains: true # S3 website and transfer endpoints ip_addresses: true # IPv4 and IPv6 addresses custom_patterns: # Application-specific patterns - pattern: "secret-[a-zA-Z0-9]+" replacement: "secret-***" description: "Mask secret tokens" For complete documentation, see Security-Focused Output Masking. Next Steps Security-Focused Output Masking - Comprehensive masking guide CLI Reference - Command-line interface guide FAQ - Frequently asked questions # FAQ **Source:** https://dev7a.github.io/samstacks/docs/faq/ **Last Updated:** 0001-01-01 Frequently asked questions about samstacks. General What is samstacks? samstacks is a YAML-driven pipeline tool for deploying AWS SAM stacks. It allows you to define a sequence of stacks in a single manifest using a GitHub Actions-style syntax, with automatic dependency resolution and parameter passing. How is samstacks different from AWS SAM? While AWS SAM deploys individual stacks, samstacks orchestrates multiple SAM stacks as a pipeline: Multi-stack coordination - Deploy related stacks in the correct order Dependency management - Automatic resolution of stack dependencies Parameter passing - Use outputs from one stack as inputs to another Conditional deployment - Deploy stacks based on expressions Pipeline-level configuration - Shared settings across all stacks Installation & Setup Do I need to install samstacks locally? No! The quickest way to use samstacks is with uvx: uvx samstacks deploy pipeline.yml This runs samstacks without any local installation or virtual environment setup. What are the prerequisites? Python 3.8+ - For running samstacks AWS CLI - Configured with appropriate permissions SAM CLI - For template validation and deployment How do I configure AWS credentials? samstacks uses the same AWS credentials as the AWS CLI and SAM CLI. Configure them using: aws configure # or export AWS_PROFILE=my-profile Pipeline Configuration Can I use existing SAM templates? Yes! samstacks works with existing SAM templates. Just point the dir field to the directory containing your template.yml file. How do I pass outputs between stacks? Use the expression syntax to reference stack outputs: stacks: - id: network dir: ./network - id: app dir: ./app params: VpcId: ${{ stacks.network.outputs.VpcId }} Can I deploy only certain stacks? Yes, use conditional expressions: stacks: - id: optional-stack dir: ./optional if: ${{ env.DEPLOY_OPTIONAL == 'true' }} Troubleshooting Stack deployment failed, what now? Check the error message - samstacks shows detailed CloudFormation errors Review stack parameters - Ensure all required parameters are provided Verify dependencies - Make sure dependent stacks deployed successfully Check AWS permissions - Ensure your credentials have the necessary permissions How do I debug expression evaluation? Use the --verbose flag to see how expressions are evaluated: uvx samstacks deploy pipeline.yml --verbose Stack is stuck in rollback state If a CloudFormation stack is in a failed state, you may need to: Delete the stack in the AWS Console Fix the template or parameters causing the issue Redeploy the pipeline Advanced Usage Can I use custom SAM configurations per stack? Yes, define sam_config at the stack level: stacks: - id: my-stack dir: ./my-stack sam_config: version: 0.1 default: deploy: parameters: capabilities: CAPABILITY_NAMED_IAM How do I run commands after deployment? Use the run field: stacks: - id: api dir: ./api run: |- echo "API URL: ${{ stacks.api.outputs.ApiUrl }}" curl -f "${{ stacks.api.outputs.ApiUrl }}/health" Can I use samstacks in CI/CD? Absolutely! samstacks works great in CI/CD pipelines. Use uvx for the simplest setup: # GitHub Actions example - name: Deploy SAM stacks run: uvx samstacks deploy pipeline.yml Security How do I protect sensitive data in deployment outputs? Use the comprehensive output masking feature to automatically mask sensitive data: pipeline_settings: output_masking: enabled: true categories: account_ids: true api_endpoints: true database_endpoints: true This protects AWS account IDs, API URLs, database endpoints, and more in console output, reports, and logs. See Security-Focused Output Masking for complete details. What types of sensitive data can be masked? samstacks can mask seven categories of sensitive data: Account IDs - 12-digit AWS account numbers API Endpoints - API Gateway and Lambda Function URLs Database Endpoints - RDS, ElastiCache, DocumentDB connection strings Load Balancer DNS - ALB, NLB, CLB DNS names CloudFront Domains - CloudFront distribution domains S3 Bucket Domains - S3 website and transfer endpoints IP Addresses - IPv4 and IPv6 addresses You can also define custom regex patterns for application-specific secrets. Does masking affect actual deployments? No, masking only affects display output, reports, and logs. The actual AWS resources and their configurations remain unchanged. Masking is purely cosmetic for security purposes. Getting Help Still have questions? Here are additional resources: GitHub Repository - Source code and issues GitHub Discussions - Community support Report Issues - Bug reports and feature requests