Getting Started

A high-level overview on template building basics with VaporShell

Setting Up VaporShell

Prerequisites

In order to install VaporShell from the PowerShell Gallery and run it successfully once installed, the following must be true:

  1. PowerShell v3.0 or greater is installed.
    • If you are running on Windows, you can check this off after confirming the installed version via running $PSVersionTable to show your PS version. Typically, you’ll only be on a lower version if you’re running Windows 7 / Server 2008 and have not upgraded WMF yet.
    • If you are not running Windows, head over to the official PowerShell GitHub page for details on how to install PowerShell on your system.
  2. The PowerShellGet module is installed.

BONUS: Support for validating the template has been added into Export-VaporShell, with create-stack planned to be added soon as well. To ensure cross-platform compatibility, these leverage the AWS CLI tools. In order to take advantage of them, you will need to have the AWS CLI tools installed, configured and available in your PATH.

Running Export-VaporShell -Path $path -VaporShellTemplate $template -ValidateTemplate would be the same as running the following command against the resulting JSON template file:

aws cloudformation validate-template --template-body fileb://$fileUrlConverted

BONUS PT 2: Want to work in YAML instead? We leverage AWSLabs’ cfn-flip to convert between JSON and YAML, as cfn-flip is cross-platform and is designed specifically for converting CloudFormation templates. Click here to check the GitHub page out; you will need to use pip to install cfn-flip

Running Export-VaporShell -Path $path -VaporShellTemplate $template -As YAML would be the same as running the following command against the resulting JSON template file:

1
2

Export-VaporShell -Path $path -VaporShellTemplate $template
cfn-flip $path | Set-Content $path -Force

Have any suggestions to extend that? Let us know! Click here to view the AWS CLI command reference for Cloudformation

Installing the Module

To install VaporShell from the PowerShellGallery, open PowerShell and run the following command:
Install-Module -Name VaporShell -Scope CurrentUser

If you would like to install for all users, run the following command in an elevated PowerShell prompt:
Install-Module -Name VaporShell

Building a VaporShell Template

Begin: Import and Initialize

The first thing you will need to do in your build script is import VaporShell into the current session:
Import-Module VaporShell

Next, you need to initialize a new template OR import an existing template to build onto:

Initialize

  • Parameters:
    • FormatVersion: Defaults to ‘2010-09-09’ – currently the only available Format Version for CloudFormation
    • Description: The description of your template.
      $template = Initialize-VaporShell -Description "CloudFormation Template 1"

OR

Import

  • Parameters:
    • Path: This is the path to your existing JSON template file
      $template = Import-VaporShell -Path ".\CFNtemplate00.json"

Process: Fill It Out

The VaporShell.Template object contains ScriptMethods to add and remove items from the template. For example, to add a resource to the template, you’ll use the AddResource() script method found on the template object. You would do the same for Parameters (AddParameter()), Metadata (AddMetadata()), Outputs (AddOutput()), etc. Need to remove something? Call the appropriate Remove*() method and pass the Logical ID of the item you are trying to remove as the parameter, i.e. $template.RemoveResource("S3Bucket"). These are covered completely in the Module Digest!

Here’s a quick conversion of an AWS sample template into VaporShell, followed by the JSON example from AWS. This template adds 1 Resource (an S3 Bucket) and 2 Outputs:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

<# Import the module #>
Import-Module VaporShell

<# Initialize the template #>
$template = Initialize-VaporShell -Description "AWS CloudFormation Sample Template S3_Website_Bucket_With_Retain_On_Delete: Sample template showing how to create a publicly accessible S3 bucket configured for website access with a deletion policy of retail on delete. **WARNING** This template creates an S3 bucket that will NOT be deleted when the stack is deleted. You will be billed for the AWS resources used if you create a stack from this template."

<# Add the S3 bucket resource to the template object #>
$template.AddResource(
    (New-VSS3Bucket -LogicalId "S3Bucket" -AccessControl "PublicRead" -WebsiteConfiguration (Add-VSS3BucketWebsiteConfiguration -IndexDocument "index.html" -ErrorDocument "error.html") -DeletionPolicy Retain)
)

<# Add multiple Outputs to the template #>
$template.AddOutput(
    # Add the WebsiteURL output
    (New-VaporOutput -LogicalId "WebsiteURL" -Value (Add-FnGetAtt -LogicalNameOfResource "S3Bucket" -AttributeName "WebsiteURL") -Description "URL for website hosted on S3"),

    # Add the S3BucketSecureURL output
    (New-VaporOutput -LogicalId "S3BucketSecureURL" -Value (Add-FnJoin -ListOfValues "https://",(Add-FnGetAtt -LogicalNameOfResource "S3Bucket" -AttributeName "DomainName")) -Description "Name of S3 bucket to hold website content")
)

JSON sample: Amazon S3 bucket with a deletion policy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

{
  "AWSTemplateFormatVersion" : "2010-09-09",

  "Description" : "AWS CloudFormation Sample Template S3_Website_Bucket_With_Retain_On_Delete: Sample template showing how to create a publicly accessible S3 bucket configured for website access with a deletion policy of retail on delete. **WARNING** This template creates an S3 bucket that will NOT be deleted when the stack is deleted. You will be billed for the AWS resources used if you create a stack from this template.",

  "Resources" : {
    "S3Bucket" : {
      "Type" : "AWS::S3::Bucket",
      "Properties" : {
        "AccessControl" : "PublicRead",
        "WebsiteConfiguration" : {
          "IndexDocument" : "index.html",
          "ErrorDocument" : "error.html"      
         }
      },
      "DeletionPolicy" : "Retain"
    }
  },

  "Outputs" : {
    "WebsiteURL" : {
      "Value" : { "Fn::GetAtt" : [ "S3Bucket", "WebsiteURL" ] },
      "Description" : "URL for website hosted on S3"
    },
    "S3BucketSecureURL" : {
      "Value" : { "Fn::Join" : [ "", [ "https://", { "Fn::GetAtt" : [ "S3Bucket", "DomainName" ] } ] ] },
      "Description" : "Name of S3 bucket to hold website content"
    }
  } 
}

End: Export and Validate

Once you have your template object filled out, the next step is to export it to a template file. At the end of your template script you would just need to add the following:

1
2
3
4
5

<# Set your template path (update to your preferred template location - this is just an example) #>
$JSON = ".\path\to\template.json"

<# Export the template to file, including -Force to overwrite an existing template (not required) #>
Export-VaporShell -Path $JSON -VaporShellTemplate $template -Force

Want to also leverage AWS CLI Tools to validate the exported template? As long as the AWS CLI Tools are installed, configured (minimum is adding the key, secret and setting the default region), you can add the -ValidateTemplate switch to the Export-VaporShell call:

1

Export-VaporShell -Path $JSON -VaporShellTemplate $template -ValidateTemplate

Diving Deeper

At this point, you’ve covered VaporShell at a high level. Head to the Module Digest to dive deeper!