Stackaroo

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.

Overview

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.

Features

Environment Management

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

Dependency Management

• Define stack dependencies with depends_on
• Automatic deployment ordering

Change Preview

• 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

Stack Information

• 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

Template Validation

• 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.

Parameter System

Stackaroo provides a comprehensive parameter system supporting multiple resolution types:

Literal Parameters

Direct string values defined in configuration:

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

Stack Output Parameters

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

Cross-Region Stack Outputs

Reference outputs from stacks in different AWS regions:

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

List Parameters

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"

Context Overrides

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

CloudFormation Template Templating

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

Real-time Event Streaming

• 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

Installation

Using Go Install

go install github.com/orien/stackaroo@latest

Download Binary

Download the latest release from the releases page.

Linux/macOS

# 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

Windows

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

Verify Installation

stackaroo --version

Quick Start

Configuration

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

Deployment

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

Key Commands

Core Commands

• 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

Global Flags

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

Usage Examples

# 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