Tips & Tricks

Helpful tips and approaches to using VaporShell

Tips, Tricks and Gotchas

Remember the Parentheses!

VaporShell is pure PowerShell and should be approached accordingly
This means that you should work with commands the same as you would on any other script. The most common case in point is wrapping your commands in parentheses when adding them in as Parameter Values. In the following example, you can see the parentheses around the full New-VaporOutput command, as well as around the value of the -Value parameter, as we’re using the Add-FnGetAtt function to add an Fn::GetAtt Intrinsic Function for the value.

1
$template.AddOutput(  (New-VaporOutput -LogicalId "WebsiteURL" -Value (Add-FnGetAtt -LogicalNameOfResource "S3Bucket" -AttributeName "WebsiteURL") -Description "URL for website hosted on S3")  )

Different Strokes

The beauty of leveraging PowerShell is that you can organize your template builds in whatever way works best for you; the only constant being that you’ll need to keep your Import-Module VaporShell at the top of the script to prevent errors from functions not being found.

Here are a couple examples of different approaches to laying out a template script:


Store your VaporShell objects in variables at the top of the script, adding them in after using the variables. This approach allows you to clearly list your resources, parameters, etc, at the top of the script

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
\# Import the module
Import-Module VaporShell

\# Store your template properties in variables
$s3Bucket = New-VSS3Bucket -LogicalId "S3Bucket" -AccessControl "PublicRead" -WebsiteConfiguration (Add-VSS3BucketWebsiteConfiguration -IndexDocument "index.html" -ErrorDocument "error.html") -DeletionPolicy Retain
$websiteUrl = New-VaporOutput -LogicalId "WebsiteURL" -Value (Add-FnGetAtt -LogicalNameOfResource "S3Bucket" -AttributeName "WebsiteURL") -Description "URL for website hosted on S3"
$s3BucketSecureUrl = New-VaporOutput -LogicalId "S3BucketSecureURL" -Value (Add-FnJoin -ListOfValues "https://",(Add-FnGetAtt -LogicalNameOfResource "S3Bucket" -AttributeName "DomainName")) -Description "Name of S3 bucket to hold website content"

\# Initialize the template and add the resource and outputs
$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."
$template.AddResource($s3Bucket)
$template.AddOutput($websiteUrl,$s3BucketSecureUrl)

\# Export and validate
$JSON = ".\path\to\template.json"
Export-VaporShell -Path $JSON -VaporShellTemplate $template -Force -ValidateTemplate -Verbose

Store your VaporShell objects in external scripts, then dot source the script files to add them to the template. This allows external resource sharing so you can cut down on code even further. Dot sourcing is critical to ensure that the external script is loaded into the current session, not called in an external process!

1
2
3
4
5
6
7
8
9
10
11
12
13
14
\# Import the module
Import-Module VaporShell

\# Sets the current location to your shared templates folder (example only)
Set-Location "C:\Templates\Shared"

\# Initialize the template and add the resource and outputs
$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."
$template.AddResource( (. ".\S3Bucket.ps1") )
$template.AddOutput( (. ".\websiteUrl.ps1"), (. ".\s3BucketSecureUrl.ps1") )

\# Export and validate
$JSON = "C:\Templates\template.json"
Export-VaporShell -Path $JSON -VaporShellTemplate $template -Force -ValidateTemplate -Verbose