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 also pull from the Gallery):

## 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.

Template Elements

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:

1. The Resource directive is used to add a resource definition to the template:

• The first parameter "iamUser" is a logical name given to the resource that should be unique within the template.
• The second parameter is one of the predefined resource types supported by CloudFormation.

The form of the Resource definition given above is known as the Generic Resource directive, and it allows you to define any supported resource, but it requires you to know the details of the resource properties and specify them in a free-form fashion.

An alternative approach is to use the Typed Resource directives -- there is one directive corresponding to each supported resource type, and they take the form of: Res-ProductName-ResourceName

For example, the equivalent Type Resource for the template above would be:

Res-IAM-User

So, the following adjusted template is equivalent to the template above.

## Template "Sample1.ps1"
ipmo AwsCfn

Template -Description "My first CFN template" -JSON {
    Res-IAM-User "iamUser"
}

In fact if you saved this updated version, and ran the following to update the existing CFN Stack, you would get an error:

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

If you ran this Stack update after successfully creating it with the earlier template, you would get the error No updates are to be performed. because CloudFormation is smart enough to know when the template JSON is identical to what is already used to define an existing Stack and doesn't try to modify it.

The Typed Resource directives give you more guidance when specifying properties for resources thanks to the built-in IntelliSense of the ISE editor. For example, by typing a - after a directive you trigger the drop-down for showing you the possible parameters that may be specified, and with type details for each one:

IntelliSense - Names and types of parameters

Additionally, for any parameters that take arguments but are restricted to a fixed set of values, you can see the complete list and even search within by typing a few characters of the value that you may want:

IntelliSense - Parameter restricted set of argument values