A PowerShell module for building, packaging and deploying AWS CloudFormation templates
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
.vscode
Docs
GitHub
Tests
VaporShell
.gitignore
CHANGELOG.md
Install-VaporShell.ps1
LICENSE
README.md
_config.yml
azure-pipelines.yml
build.ps1
psake.ps1

README.md

VaporShell




📝        📦        🚀
Build | Package | Deploy
A PowerShell module for building, packaging and deploying AWS CloudFormation templates ☁️

Azure Pipelines      Coveralls.io - Code Coverage     PowerShell Gallery - Install VaporShell     Gitter - Chat     Slack - Chat     Slack - Status
Built with ❤︎ by Nate Ferrell. Looking for contributors!

Table of Contents

Features

  • built from AWS's CloudFormation spec sheet: 100% coverage of all available resource and property types
  • runs on any OS: developed and tested in Windows, Ubuntu, and macOS on PowerShell v3-6
  • validates everything: built to make resulting templates reliable by leveraging parameter validation built into PowerShell
  • goes turbo: package and deploy your templates fast with one command: vsl vaporize

Prerequisites

  • PowerShell 3+
  • .NET 4.5.0+ OR .netstandard 1.3+
    • if you have PowerShell 4 or greater, you're covered!

Recommended: AWS Labs cfn-flip

If you are working with YAML templates, you need to install cfn-flip. VaporShell uses cfn-flip under the hood to work with YAML templates, as PowerShell does not natively support YAML at this time. If you are only working in JSON, then cfn-flip isn't necessary.

Installation

On PowerShell 5+ or have PowerShellGet installed? Install directly from the PowerShell Gallery:

Install-Module VaporShell -Scope CurrentUser

Not on PowerShell 5+ and can't install PowerShellGet? You're covered as well:

Invoke-Expression (New-Object Net.WebClient).DownloadString("https://raw.githubusercontent.com/scrthq/VaporShell/master/Install-VaporShell.ps1")

Please inspect code before you run it. Here's a handy link to that raw content for you to review: Install-VaporShell.ps1.

Tips

Working with Credentials

If you are planning on packaging or deploying to CloudFormation, you will need to setup credentials in your local Shared Credentials file. If you are using the AWS command-line interface (CLI) and already have setup credentials, then you should be ready to go.

You can update or add a credential profile with Set-VSCredential:

Set-VSCredential -AccessKey $accessKey -SecretKey $secretKey -Region USWest1 -ProfileName DevAccount

Bare Necessities

When building templates with VaporShell, there are typically a few items that you'll want to include in your build script:

  1. Create a template object by calling one of these into a variable
    • $template = Initialize-VaporShell
      • Use when starting from scratch
    • $template = Import-VaporShell -Path .\template.json
      • Use when importing from an existing template to build off of
  2. Build out your template by using the object's ScriptMethods:
    • $template.AddResource()
    • $template.AddParameter()
    • $template.AddOutput()
    • etc....
  3. Export your template to local file or stdout (useful for piping directly into New-VSStack or other functions that support TemplateBody as pipeline input)
    • Export-VaporShell -VaporshellTemplate $template -Path .\template.json
      • This will output the template as template.json in your working directory
    • Export-VaporShell -VaporshellTemplate $template
      • This will output the template to stdout as a single string
    • $template.ToJSON()
      • This script method on the template object performs the same function as Export-VaporShell -VaporshellTemplate $template and outputs the string template as JSON to stdout
    • $template.ToYAML()
      • This does the same thing as the ToJSON() script method, but outputs to YAML (cfn-flip required)

Examples

#1 Initialize a VaporShell object
$vsl = Initialize-VaporShell -Description "A function triggered on a timer."

#2 Add a Serverless function with local code as the CodeUri and a schedule of 5 minutes (split into multiple lines for readability)
$samFunction = New-SAMFunction `
    -LogicalId "ScheduledFunction" `
    -Handler "index.handler" `
    -Runtime "nodejs6.10" `
    -CodeUri ".\code" `
    -Events (Add-SAMScheduleEventSource -LogicalId Timer -Schedule "rate(5 minutes)")
$vsl.AddResource($samFunction)
$TemplateFile = ".\sched-func.yaml"

#3 Save the template as YAML using the VaporShell object's ToYAML() method (uses cfn-flip to convert to/from YAML)
$vsl.ToYAML($TemplateFile)

<#4 Package and deploy (vsl vaporize) the template file (--tf $TemplateFile) as a change set with parameters:
    - stack name (--sn) 'sched-func'
    - S3 bucket also named 'sched-func' (defaults to the stack name if --s3 is not passed)
    - capabilities: CAPABILITY_IAM (--caps iam)
    - Verbose (--v) enabled
    - Force (--f) enabled (make sure that the bucket is created and objects are uploaded)
    - Watch (--w) the stack events in colorized output after executing the change
#>
vsl vaporize --tf $TemplateFile --sn sched-func --caps iam --v --f --w

Check out the Examples page for more.

In Action

This is a deployment being watched via Watch-Stack $stackName to show stack creation and deletion mid-deploy: Watch-Stack in action

License

Apache 2.0

Changelog

Changelog