This content is part of the Essential Guide: The go-to Windows PowerShell guide

Automate tasks with AWS PowerShell tools

Administrators can put Windows to use with the AWS PowerShell module. They can automate EC2 instance configuration, but must follow the necessary security steps.

Most IT administrators who manage Windows-based servers are familiar with Windows PowerShell. And PowerShell expertise...

can transfer over to AWS management. AWS Tools for Windows PowerShell contains thousands of cmdlets that work with most AWS utilities. This tip examines how to use AWS Tools for Windows PowerShell, specifically for configuring Elastic Compute Cloud instances.

Until recently, the PowerShell module was only an option on Windows systems. However, Microsoft open sourced PowerShell and is making it available on all major platforms including Linux and Mac OS X. To support using AWS PowerShell Tools, Amazon will release the AWS Tools for PowerShell Core Edition but will continue to offer the AWS Tools for Windows PowerShell.

Installation and setup

AWS Tools for Windows PowerShell is installed on newly launched Windows-based Elastic Compute Cloud (EC2) instances. If a developer is doing script development on a local Windows machine, he can install the components in one of two ways.

1. Use the MSI installer that will provide both the AWS .NET SDK as well as the AWS PowerShell module.

2. AWS provides support for the PowerShell Gallery, which is Microsoft's central online repository for PowerShell content. If a developer is running Windows Management Framework 5.0, which includes PowerShell 5.0, he can install the AWS PowerShell module with a single line in the command-line interface:

Install-Module AWSPowerShell

The new AWS Tools for PowerShell Core Edition will be available through the PowerShell Gallery. At the time of this writing, the new module has not yet been published to the gallery. Watch the AWS .NET SDK blog for updates and instructions as AWS works toward a final release for those AWS PowerShell tools.

Specifying credentials for AWS PowerShell tools

Before running the cmdlets, a developer provides his credentials. In the case of EC2 instances where the tools are already installed, attach an AWS Identity and Access Management role to the instance to provide the permissions needed to run the cmdlets. If a developer is working on his own machine, he needs to specify the credentials either explicitly or through a credential profile.

Every AWS cmdlet provides AccessKey and SecretKey parameters, but it's easier and safer to create a credential profile. This allows a developer to omit these parameters from individual commands and also removes the risk of embedding keys in the script's source code.

One of the most common automation tasks is provisioning EC2 instances. Before a developer can launch an instance with AWS PowerShell tools, he needs to know which Amazon Machine Image to use.

The most common method of storing credentials in a profile is to use the SDK store, which encrypts credentials and stores them under the home folder. For example, the following command will add a new profile to the SDK store:

Set-AWSCredentials -AccessKey <access key> -SecretKey <secret key> -StoreAs Development

In this example, credentials are stored in a profile called Development. A developer can create as many profiles as needed. Some enterprises may want separate profiles for different environments, such as QA, staging and production. To use a specific profile for a single command, use the ProfileName parameter:

Get-EC2Instance -ProfileName Development –Region us-west-2

A developer can also use the recommended approach: initializing the shell defaults so he doesn't have to explicitly set the profile name for every command. This is done using the Initialize-AWSDefaults cmdlet:

Initialize-AWSDefaults -ProfileName Development -Region us-west-2

In this example, the Region parameter is set to us-west-2. This parameter, like the AccessKey and SecretKey parameters, can be overridden on a per-command basis.

Searching for AMIs

One of the most common automation tasks is provisioning EC2 instances. Before a developer can launch an instance with AWS PowerShell tools, he needs to know which Amazon Machine Image (AMI) to use. The image ID, specifically, is important to determine.

Using the Get-EC2ImageByName cmdlet makes it easy to find Windows-based images. This cmdlet will simply return a list of friendly image names, such as WINDOWS_2012R2_BASE or WINDOWS_2008R2_BASE. Use this to retrieve the image ID.

Because AWS updates Windows AMIs monthly, image IDs will change on a regular basis. These IDs are also different in every AWS region. Therefore, an easy way to get the correct image ID for a particular platform is shown here:

$ami = Get-EC2ImageByName windows_2012r2_base | Select-Object -ExpandProperty imageid

In this example, the Get-EC2ImageByName retrieves the image ID for the Windows Server 2012 R2 base image. We also expand the ImageId property so that the variable will contain a flat string equal to the image ID. This command can run in any region and should always contain the latest image ID for the selected OS.

After deciding which image ID to use, it's fairly straightforward to create an EC2 instance. We simply need to use the New-EC2Instance cmdlet. This cmdlet provides lots of parameters that control how the instance is created. Developers create an instance in the default Amazon Virtual Private Cloud using the following single line of code:

New-EC2Instance -ImageId $ami -KeyName Oregon -InstanceType m4.xlarge

This command assumes the key pair was created in the us-west-2 region called Oregon.

Creating security groups and managing rules

If developers don't specify a security group to use when launching an instance, the instance will use the default security group. Launching an instance into a specific group requires the security group ID. In the example below, a new security group is created and the resulting ID is captured in a variable.

$sg = New-EC2SecurityGroup -GroupName MyRDPGroup -Description 'Enable RDP from Internet'

Keep in mind there are no rules using this method to create a group. To use the Remote Desktop Protocol to connect to an instance in this group as soon as it becomes available, add a single rule to the group that permits TCP port 3389, as shown here:

$ip = New-Object Amazon.EC2.Model.IpPermission
$ip.IpProtocol = 'tcp'
$ip.FromPort = '3389'
$ip.ToPort = '3389'

Here we create a new IpPermission object with the New-Object cmdlet. Use dot notation to define the required property values for the rule. Notice that the last line specifies the source address. As a best practice, use your own IP address or subnet CIDR range to secure instances. To do so, replace, which means any source IP, with your own information.

To create multiple rules, produce multiple IpPermission objects and add them to the rule using the Grant-EC2SecurityGroupIngress cmdlet.

Grant-EC2SecurityGroupIngress -GroupId $sg -IpPermissions $ip

To assign multiple rules, supply a comma-separated list of IpPermission objects to the IpPermissions parameter. Then launch an EC2 instance into the security group using the following command:

New-EC2Instance -ImageId $ami -KeyName Oregon -InstanceType m4.xlarge -SecurityGroupId $sg

Test your knowledge about the AWS PowerShell command line

Quiz yourself on the nuances of Powershell v3, as the command-line shell becomes the management standard.

Tagging EC2 instances

Tagging helps developers keep track of instances in several ways. It's recommended to use the Name tag so the instance name matches the server's host name when viewing it in the console. To do this through PowerShell, supply the instance ID as well as a hash table that contains a key/value pair for the server name and the desired value.

$i = New-EC2Instance -ImageId $ami -KeyName Oregon -InstanceType m4.xlarge
New-EC2Tag -Resources $i.instances.instanceid -Tags @{key='Name';value='SRV01'}

In this example, we created an instance and stored the resulting reservation object in the $i variable. This gives admins an easy way to reference the instance ID in the next command, which uses the New-EC2Tag cmdlet to assign a Name tag with the value of SRV01 to the instance.

If a developer already created an instance but needs to reference the instance ID, he can find it using the Get-EC2Instance cmdlet.

Next Steps

How to run Oracle on AWS

These AWS CLI tools boost app development

Using Spark helps utilize big data

How to filter for S3 files with PowerShell

Dig Deeper on AWS tools for development