Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/orien/stackaroo

A jumping command-line tool that facilitates managing AWS CloudFormation stacks via infrastructure as code. :kangaroo:
https://github.com/orien/stackaroo

aws-cloudformation configuration-as-code

Last synced: 5 months ago
JSON representation

A jumping command-line tool that facilitates managing AWS CloudFormation stacks via infrastructure as code. :kangaroo:

Awesome Lists containing this project

README 

          
# Stackaroo



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



📚 **[Read the user documentation](https://orien.github.io/stackaroo/)** 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:



```bash

# 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:

```yaml

parameters:

  Environment: production

  InstanceType: t3.medium

  Port: "8080"

```



#### Stack Output Parameters

Pull values dynamically from existing CloudFormation stack outputs:

```yaml

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:

```yaml

parameters:

  SharedBucketArn:

    type: stack-output

    stack: shared-resources

    output: BucketArn

    region: us-east-1

```



#### List Parameters

Support for CloudFormation `List` and `CommaDelimitedList` parameters with mixed resolution types:

```yaml

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:

```yaml

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:



```yaml

# 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



```bash

go install github.com/orien/stackaroo@latest

```



### Download Binary



Download the latest release from the [releases page](https://github.com/orien/stackaroo/releases).



#### Linux/macOS



```bash

# 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



```bash

stackaroo --version

```



## Quick Start



### Configuration



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



```yaml

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:



```bash

# 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  [stack-name]` - Deploy all stacks or a specific stack with dependency-aware ordering and integrated change preview

- `diff  ` - Preview changes between deployed stack and local configuration

- `describe  ` - Display detailed information about a deployed CloudFormation stack

- `validate  [stack-name]` - Validate CloudFormation templates for syntax and AWS-specific requirements

- `delete  [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

```bash

# 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

```