A command-line tool for managing AWS CloudFormation stacks as code.

📚 Read the user documentation for tutorials, how-to guides, explanations, and detailed reference material.

Stackaroo simplifies CloudFormation stack management through declarative YAML configuration, allowing you to define your infrastructure once and deploy it consistently across multiple environments. It provides comprehensive parameter management with support for literal values, dynamic stack output resolution, and cross-region references. Features include dependency-aware deployment ordering, integrated change previews, template validation, and real-time event streaming during stack operations.

• Deploy the same templates across multiple contexts
• Different AWS regions and parameters per context

• Define stack dependencies with depends_on
• Automatic deployment ordering

• Comprehensive Change Analysis: Shows template, parameter, tag, and resource changes
• Unified Template Diff: Line-by-line template comparison in unified diff format (similar to git diff)
• CloudFormation ChangeSet Integration: Uses AWS ChangeSet API for accurate previews
• Rich Diff Output: Detailed comparison of current vs proposed infrastructure
• Resource Impact Assessment: Identifies which resources will be created, modified, or deleted
• Replacement Warnings: Highlights resources that require replacement during updates
• Consistent Formatting: Same preview format as the dedicated diff command

• Comprehensive Stack Details: View complete information about deployed CloudFormation stacks
• Status and Metadata: Shows stack status, creation time, last update, and description
• Parameter Display: Current parameter values sorted alphabetically
• Output Information: Stack outputs with their current values
• Tag Management: All stack tags displayed in organised format
• Human-Readable Format: Clean, consistent formatting with proper indentation
• Real-time Data: Retrieves current information directly from AWS CloudFormation

• Fast Feedback: Validate CloudFormation templates without deployment
• AWS API Integration: Uses CloudFormation ValidateTemplate API for accurate validation
• Syntax Checking: Catches template syntax errors and invalid resource types
• Batch Validation: Validate all stacks in a context with a single command
• CI/CD Ready: Perfect for pre-deployment checks in automated pipelines
• Regional Validation: Validates templates in the context's target region
• Clear Output: Progress indicators and summary reports for validation results

Validate templates early in your development workflow:

# Validate a single stack's template
stackaroo validate dev vpc
# Validate all stacks in a context
stackaroo validate production

The validation command provides immediate feedback on template errors without requiring actual deployment, making it ideal for development workflows and continuous integration pipelines. It processes templates through the same resolution pipeline as deployment, including Go template processing, ensuring validation matches what will actually be deployed.

Stackaroo provides a comprehensive parameter system supporting multiple resolution types:

Direct string values defined in configuration:

parameters:
 Environment: production
 InstanceType: t3.medium
 Port: "8080"

Pull values dynamically from existing CloudFormation stack outputs:

parameters:
 VpcId:
 type: stack-output
 stack: networking
 output: VpcId
 DatabaseEndpoint:
 type: stack-output
 stack: database
 output: DatabaseEndpoint

Reference outputs from stacks in different AWS regions:

parameters:
 SharedBucketArn:
 type: stack-output
 stack: shared-resources
 output: BucketArn
 region: us-east-1

Support for CloudFormation List<Type> and CommaDelimitedList parameters with mixed resolution types:

parameters:
 # Mix literals and stack outputs in a single list parameter
 SecurityGroupIds:
 - sg-baseline123 # Literal value
 - type: stack-output # Dynamic from stack output
 stack: security-stack
 output: WebSGId
 - sg-additional456 # Another literal
 # Simple literal list
 AllowedPorts:
 - "80"
 - "443"
 - "8080"

Different parameter values per deployment context:

parameters:
 InstanceType: t3.micro # Default value
contexts:
 production:
 parameters:
 InstanceType: t3.large # Production override

Benefits:

• Automatic Resolution: Stack outputs resolved at deployment time
• Cross-Stack Dependencies: Reference outputs from other stacks seamlessly
• Environment Flexibility: Different values per context without template changes
• Type Safety: Comprehensive validation and error handling
• Backwards Compatible: Existing literal parameter configurations work unchanged

Stackaroo supports dynamic CloudFormation template generation using Go templates with Sprig functions. This allows you to use the same template file across different contexts with context-specific variations:

# Template: templates/storage.yaml
AWSTemplateFormatVersion: '2010年09月09日'
Description: {{ .Context | title }} storage for {{ .StackName }}
Resources:
 AppBucket:
 Type: AWS::S3::Bucket
 Properties:
 BucketName: {{ .StackName }}-bucket-{{ .Context | lower }}
 Tags:
 - Key: Environment
 Value: {{ .Context }}
{{- if eq .Context "production" }}
 - Key: BackupEnabled
 Value: "true"
{{- end }}

When deployed to the development context, this generates a bucket named my-app-bucket-development. When deployed to production, it generates my-app-bucket-production with an additional backup tag.

Available features:

• Context variables: Access {{ .Context }} (the context name like "development" or "production") and {{ .StackName }} (the stack name) in templates
• Sprig functions: Use upper, lower, title, and other text transformations
• Conditionals: {{- if eq .Context "production" }} for environment-specific resources
• Automatic processing: All templates are processed automatically, backwards compatible with static templates

• See exactly what will change before applying
• Live CloudFormation events during deployment operations
• See resource creation, updates, and completion status in real-time
• Smart detection of create vs update operations
• Graceful handling of "no changes" scenarios

go install github.com/orien/stackaroo@latest

Download the latest release from the releases page.

# Download and install (replace VERSION and ARCH as needed)
VERSION=1.0.0
ARCH=linux-x86_64
URL="https://github.com/orien/stackaroo/releases/download/v${VERSION}/stackaroo-${VERSION}-${ARCH}.tar.gz"
DIR="stackaroo-${VERSION}-${ARCH}"
curl -sL "$URL" | tar -xz
sudo mv "${DIR}/stackaroo" /usr/local/bin/
rm -rf "${DIR}"
# Verify installation
stackaroo --version

Download the .zip file from the releases page, extract it, and add the binary to your PATH.

stackaroo --version

Create a stackaroo.yaml file defining your stacks and contexts:

project: my-infrastructure
region: us-east-1
contexts:
 development:
 account: "123456789012"
 region: ap-southeast-4
 tags:
 Environment: development
 production:
 account: "987654321098"
 region: us-east-1
 tags:
 Environment: production
stacks:
 vpc:
 template: templates/vpc.yaml
 parameters:
 # Literal parameters
 Environment: development
 VpcCidr: "10.0.0.0/16"
 EnableDnsSupport: "true"
 contexts:
 production:
 parameters:
 Environment: production
 VpcCidr: "172.16.0.0/16"
 app:
 template: templates/app.yaml
 parameters:
 # Literal parameters
 InstanceType: t3.micro
 MinCapacity: "1"
 MaxCapacity: "3"
 # Stack output parameters (pull from existing stacks)
 VpcId:
 type: stack-output
 stack: vpc
 output: VpcId
 PrivateSubnetId:
 type: stack-output
 stack: vpc
 output: PrivateSubnet1Id
 # Cross-region stack output (optional region parameter)
 SharedBucketArn:
 type: stack-output
 stack: shared-resources
 output: BucketArn
 region: us-east-1
 contexts:
 production:
 parameters:
 InstanceType: t3.small
 MinCapacity: "2"
 MaxCapacity: "10"
 depends_on:
 - vpc

Deploy stacks using either pattern:

# Deploy all stacks in a context (with dependency ordering)
stackaroo deploy development
# Deploy a specific stack
stackaroo deploy development vpc
# Preview changes before deployment
stackaroo diff development app
# View detailed stack information
stackaroo describe production vpc

• deploy <context> [stack-name] - Deploy all stacks or a specific stack with dependency-aware ordering and integrated change preview
• diff <context> <stack-name> - Preview changes between deployed stack and local configuration
• describe <context> <stack-name> - Display detailed information about a deployed CloudFormation stack
• validate <context> [stack-name] - Validate CloudFormation templates for syntax and AWS-specific requirements
• delete <context> [stack-name] - Delete stacks with dependency-aware ordering and confirmation prompts

• --config, -c - Specify config file (default: stackaroo.yaml)
• --verbose, -v - Enable verbose output for detailed logging
• --version - Show version information
• --help - Show help for any command

# Deploy all stacks in development context
stackaroo deploy development
# Deploy specific stack with verbose output
stackaroo deploy production app --verbose
# Preview changes before deployment
stackaroo diff staging vpc
# View detailed stack information
stackaroo describe production app
# Validate templates before deployment
stackaroo validate development vpc
# Validate all templates in a context
stackaroo validate production
# Delete specific stack with confirmation
stackaroo delete development app
# Delete all stacks in context (reverse dependency order)
stackaroo delete development
# Use custom config file
stackaroo deploy production --config custom-config.yaml