Documentation
FAQ

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

  1. Check the error message - samstacks shows detailed CloudFormation errors
  2. Review stack parameters - Ensure all required parameters are provided
  3. Verify dependencies - Make sure dependent stacks deployed successfully
  4. 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:

  1. Delete the stack in the AWS Console
  2. Fix the template or parameters causing the issue
  3. 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:

Manifest Reference