Usage

Usage

Being just regular CloudFormation templates, there is nothing special about their usage, however, effective usage suggests to provision templates via Amazon S3 buckets, which necessarily need to be hosted in the region the templates are going to be used in.

Accordingly, cross region operations are an essential precondition for operating the templates, so here are a few tools and snippets how to achieve this.

## Tools

All scripting will be handled via Python (cross platform) or PowerShell (Windows only, unfortunately) due to these being supported very well by AWS. In particular, the following tools will be used one way or another, please refer to their resepctive installation instructions:

• Python (cross platform)
• AWS Command Line Interface
• HTTPie (a CLI, cURL-like tool for humans)
• jq (jq is a lightweight and flexible command-line JSON processor)
• PowerShell (Windows)
• AWS Tools for Windows PowerShell
• Fabric - the Python scripting is currently orchestrated via Fabric tasks
• Vagrant - a readily configured development environment is provided via a Vagrant VM

## Getting Started

The easiest way to getting started with a readily configured environment for StackFormation development is by means of the provided Vagrant virtual machine (VM) - if you are familiar with Vagrant all you need to do is

1. Install Vagrant
2. Install Salty Valgrant (a Salt provisioner)

vagrant plugin install vagrant-salt

• this is only required until the Salt provisioner has been migrated to Vagrant core, see https://github.com/saltstack/salty-vagrant/issues/72

1. Initialize Vagrant VM as usual

vagrant up

1. Log into the VM and use Fabric to discover available tasks

vagrant ssh
cd /vagrant
fab -l

1. This currently yields

This is the StackFormation build script based on Fabric (http://fabfile.org/).

Available commands:

    create_buckets        Create required S3 buckets.
    download_aws_samples  Download the AWS CloudFormation sample templates.
    list                  List templates.
    test                  Run all unit tests and doctests.
    upload                Upload templates to existing S3 buckets.
    validate_body         Validate templates via body upload.
    validate_buckets      Validate that required S3 buckets exist.
    validate_url          Validate templates via URLs of S3 objects.

Snippets

• All samples will use the Parameter_Validate.template, which executes quickly and has does not create any billable AWS Resources; download it now via your browser or
• HTTPie

http --download \
 https://s3.amazonaws.com/cloudformation -templates-us-east-1/Parameter_Validate.template

• PowerShell

Start-BitsTransfer `
 https://s3.amazonaws.com/cloudformation-templates-us-east-1/Parameter_Validate.template

• Bucket names must be unique across S3 - including a topic prefix, your domain name and a region suffix is a good way to achieve this while retaining a reasonable sort order of related buckets, e.g. the pattern <prefix>-<domain>-<suffix> would yield cfn-example-com-us-east-1.

### Via the AWS Command Line Interface (CLI)

See AWS Command Line Interface:

The AWS Command Line Interface (CLI) is a unified tool to manage your AWS services. With just one tool to download and configure, you will be able to control multiple AWS services from the command line and automate them through scripts.

1. Prepare variables

regions=`aws --region us-east-1 ec2 describe-regions | jq .Regions[].RegionName | sed s/\"//g`
bucketName="cfn-example-com"
bucketURL="https://$bucketName-{0}.s3.amazonaws.com/"
template=`cat Parameter_Validate.template`
key="templates/$template"
stackName="parameter-validate-test-1"

1. Create S3 Buckets in all regions

for region in $regions; do
  aws --region $region s3 create-bucket --bucket $bucketName-$region --create-bucket-configuration '{ "location_constraint": "$region" }';
done

1. Upload a template to all regions

for region in $regions; do
  aws --region $region s3 put-object --bucket $bucketName-$region --key $key -body "$template";
done

1. Validate a template in all regions (could be constrained to just one region of course)

for region in $regions; do
  aws --region $region cloudformation validate-template --template-body "$template";
done

1. Start a stack in all regions (most simple example - there is much more to this usually, i.e. parameters, tags and notifications)

for region in $regions; do
  aws --region $region cloudformation create-stack --stack-name $stackName --template-body "$template";
done

### Via the AWS Toolkit for Windows PowerShell

See AWS Tools for Windows PowerShell:

The AWS Tools for Windows PowerShell lets developers and administrators manage their AWS services from the Windows PowerShell scripting environment. Now you can manage your AWS resources with the same Windows PowerShell tools you use to manage your Windows environment.

1. Prepare variables

$regions = Get-AWSRegion
$bucketName = "cfn-example-com"
$bucketURL = "https://$bucketName-{0}.s3.amazonaws.com/"
$template = "Parameter_Validate.template"
$key = "templates/$template"
$stackName = "parameter-validate-test-1"

1. Create S3 Buckets in all regions

$regions | foreach {
 New-S3Bucket -Region $_.Region -BucketName "$bucketName-$($_.Region)"
}

1. Upload a template to all regions

$regions | foreach {
 Write-S3Object -Region $_.Region -BucketName "$bucketName-$($_.Region)" -Key $key -File $template
}

1. Validate a template in all regions (could be constrained to just one region of course)

$regions | foreach {
 $templateURL = [string]::Format($bucketURL + $key, $_.Region);
 Validate-CFNTemplate -Region $_.Region -TemplateURL $templateURL
}

1. Start a stack in all regions (most simple example - there is much more to this usually, i.e. parameters, tags and notifications)

$regions | foreach {
 $templateURL = [string]::Format($bucketURL + $key, $_.Region);
 New-CFNStack -StackName $stackName -Region $_.Region -TemplateURL $templateURL
}