clon

README

clon (cloudformation) is a AWS CloudFormation template and stack management tool.

Table of conent

• Overview
• Concepts
  • Config
  • Bootstrap Stack
  • Files
  • Variables
  • Template Rendering
  • Strong and week Dependencies
• Installing
• Usage
• Examples

Overview

clon is a AWS CloudFormation stack management and deployment tool. Multiple stacks and cross-dependencies can be managed from single place.

Concepts

Config

The list of stacks and their dependencies are defined in config file (default: config.yml).

The configuration syntax is following

Top level config options

Name - required - (string)
Name of the deployment. This value is used as a prefix for all stack names.

AccountID - (string)
clon will make sure that current AWS account is matching to AccountID.

Bootstrap - required - (Stack)
The bootstrap stack configuration.

Files - (map[string]File)
Map of files to upload. After files are uploaded (or syned), the information about file is exposed to template rendering.

Stacks - (list[Stack])
List of stacks managed by clon.

Variables - (map[string]string)
Map of variables. Varables are available in template rendering.

Stack

• Name - required
  The name of the stack.
• Capabilities - (list[string])
  List of stack capabilities. Allowed values are CAPABILITY_IAM and CAPABILITY_NAMED_IAM
• Template - required - (String)
  Location of template file
• RoleARN - (String)
  Location of template file
• Parameters - (map[String]String)
  Map of stack parameters
• Tags - (map[String]String)
  Map of stack tags

File

• Src - required - (String)
  Path of the template file.
• Bucket - (String) - defaults to: bootstrap.Outpus.Bucket
  Destination S3 bucket name.
• Key - (String)
  defaults to: name of the file
  S3 bucket key.

Bootstrap Stack

Bootstrap stack is a special stack, which is used to prepare AWS environment for cloudformation deployment. This template usually includes some S3 buckets for intermediate file storage and IAM roles and policies for cloudformation stacks.

This stack must contain Bucket output, which holds the name of that bucket for temporary storage.

Example of Bootstrap

Files

Files are synced to Dst S3 buckets and location information is available in templates. Files are exposed to template as following structure:

File:
  $MapKey:
    Bucket:       # Name of the bucket
    Key:          # Key of the file in bucket
    VersionID:    # Version ID of file
    Hash:         # MD5 hash of file
    ContentType:  # Content-type of file (optional)
    Region:       # Region of the bucket
    URL:          # URL to file. Can be used for nested-stacks.

Example of Files

Variables

Variables is simple map[string]string structure. They are exposed to templates as following structures:

Var:
  $MapKey: $Value

Template Rendering

RoleARN, Parameters and Tags attributes of stack configuration are rendered using golang templating with sprig support.

clon also adds following functions to rendering engine

file - read content of file.

Example: {{ file "path.txt" }}

stack - get stack data. Note, that target stack must be deployed before stack data can be used.

Example: {{ (stack "bootstrap").Outputs.Bucket }}

Strong and week Dependencies

There are many ways of creating dependency between two stacks, but overall they can be categorized as strong and week dependencies.

Strong

Strong dependencies are Nested stack dependencies or dependencies created by Export output attribute.

Nested Stacks

Nested stack dependencies are easy to manage, because CloudFormation will take care for update propagation. But they don't support planning, so it's impossible to identify exactly which resources in nested stacks will be affected.

Export

Exported outpus can be imported by other stacks. This means, that those can be trated as separate stacks and change plan can be built. But exported outpus cannot be modified, until there is any dependent stack exists. So, in order to update exported output, one should first remove all dependencies, update relevant resources and create dependencies again. This process includes many manual steps and not easy to automate.

Weak dependencies

In order to laverage from both features, change planning and automatic updates (if possible), weak reference can be used. The idea behind, is to store the output of one stack in some intermediate storage (like S3 bucket or directly via clon) and update the dependent stack separately with new value.

Note, that this kind of dependency can be created only if dependent resource will not be affected by temporary outdated value.

Example of weak dependency with clon

Installation

Get it installed with golang

go get github.com/spirius/clon/cmd/clon

Or download from releases page.

Usage

clon is a CLoudFormatiON stack management tool

Usage:
  clon [command]

Available Commands:
  deploy      Deploy stack
  destroy     Destroy stack
  execute     Execute previously planned change
  help        Help about any command
  init        Initialize bootstrap stack
  list        List stacks
  plan        Plan stack changes
  status      Show stack status
  version     show version information

Flags:
  -c, --config string            Config file (default "config.yml")
  -e, --config-override string   Override config file
  -d, --debug                    Enable debug mode
  -h, --help                     help for clon
  -i, --input                    User input availability. If not specified, value is identified from terminal. (default true)
  -t, --trace                    Enable error tracing output

Use "clon [command] --help" for more information about a command.