Getting Started

Install Module(s)

The easiest and quickest way to get started with this PowerShell module is to install it from the PowerShell Gallery. Make sure you also have the AWS Tools for Windows PowerShell installed as well (which you can pull from the Gallery as well):

## If you don't already have the AWSPowerShell module...
Install-Module -Name AWSPowerShell

## Install this AWS CFN tools module
Install-Module -Name AwsCfn

Writing a Template Script

To take full advantage of the power that you gain by using AwsCfn, you should author your templates in the PowerShell ISE (Integrated Scripting Environment), or a similar PS editor that provides IntelliSense and other editing assistive features.

In a PowerShell session, you should import the AwsCfn module, so that its cmdlets are available:

Import-Module AwsCfn

Start your template with the Template directive, giving it a description and a template block:

Template -Description "My first CFN template" {
  ## Template block
}

Within the template block, you can specify any of the template section directives that comprise the CloudFormation template anatomy:

• Parameter
• Mapping
• Condition
• Resource
• Output

For example, the following simple template only describes a single resource, an IAM User:

## Template "Sample1.ps1"
ipmo AwsCfn

Template -Description "My first CFN template" -JSON {
    Resource "iamUser" AWS::IAM_:User
}

To create a new CFN stack based on this template, from the same directory where this template is saved in a file named Sample1.ps1, you would execute:

New-CFNStack -StackName "Sample1" -TemplateBody (.\Sample1.ps1) -Capability CAPABILITY_IAM

NOTE: If you try to run the PS cmdlet to create the new CFN Stack, you may get the errors No credentials specified or obtained from persisted/shell defaults and/or No region specified or obtained from persisted/shell defaults..

Whenever you invoke any of the cmdlets in the AWS PowerShell module that interact with the AWS environment, you need to make sure the cmdlets have enough context to be able to resolve your credentials and the target AWS Region. There are numerous ways that you can specify these two attributes, so please reference the details for credentials and Regions.

In the examples on this Wiki, we assume that credentials and Region details are resolved in any AWS cmdlet invocation.

Shortly after running this cmdlet, you should be able to see in the AWS console for CloudFormation that the Stack was successfully created, and in the console for IAM that a user was created associated with this Stack.

Let's dissect the details here...

The Template Script file Sample1.ps1:

1. The script imports the AwsCfn module with ipmo AwsCfn -- the cmdlet ipmo is just an alias for Import-Module, the same cmdlet we ran above to load the module definitions and cmdlets into our session. This is needed for the template to resolve module references.
2. The Template directive is given with two (2) parameters:

• -Description - you can provide an optional description for the template that will be persisted with the Stack.
• -JSON - by default when you define a Template it returns a structured object with lots of details including the template body. By giving it the JSON flag it will convert this structured object into a JSON representation of the CFN template.
• There are other optional parameters you can pass to a Template directive, including:
  • -Version - by default the template version string 2010-09-09 is emitted but can override this
  • -Metadata - you can provide an optional dictionary object to attach arbitrary meta data to the stack, including nested arrays and dictionaries.
  • -Compress - augments the -JSON output flag to compress the resulting JSON output, stripping out insignificant whitespace

Template -Description "My first CFN template" -JSON {