Getting Started with AWS Tools for Windows PowerShell

Admins who run Windows on their desktop or laptop computer can use the AWS Tools for Windows PowerShell to perform their Amazon Web Services administration.

Installing the AWS Tools for Windows PowerShell

The pre-requisites for the AWS Tools for Windows PowerShell are minimal. Windows XP or later, with PowerShell 2.0 or later, is the requirement, so that is a pretty low bar.

Anything from Windows 7 or Windows Server 2008 R2 and up already meets these requirements, so there’s little to do but download the MSI from Amazon Web Services and install it.

If you’ll be doing the installation across multiple computers or want to automate it I’ve also published a PowerShell script to install the AWS Tools for PowerShell.

Loading the AWS Module

Before we can use any of the AWS PowerShell cmdlets we need to load the module in our PowerShell session. To do this we run Import-Module:

PS C:> Import-Module "C:\Program Files (x86)\AWS Tools\PowerShell\AWSPowerShell\AWSPowerShell.psd1"

Instead of manually running that every time we open a new PowerShell window it is more efficient to include it in your PowerShell profile. Here is the code I added to my profile to handle the AWS module:

#Load the AWS Module

$AWSModulePath = "C:\Program Files (x86)\AWS Tools\PowerShell\AWSPowerShell\AWSPowerShell.psd1"

If (Test-Path $AWSModulePath)
{
    try {
	    Import-Module $AWSModulePath -ErrorAction STOP
    }
    catch
    {
	    Write-Warning $_.Exception.Message
    }
}
else
{
    Write-Warning "The AWS PowerShell module was not found on this computer."
}

Managing AWS Credentials

With the AWS module loaded we can run any cmdlet that we want to, but it won’t work because there are no AWS credentials specified yet.

PS C:\Scripts> Get-S3Bucket
Get-S3Bucket : Access Denied
At line:1 char:1
+ Get-S3Bucket
+ ~~~~~~~~~~~~
    + CategoryInfo          : InvalidOperation: (Amazon.PowerShe...tS3BucketCmdlet:GetS3BucketCmdlet) [Get-S3Bucket],
   InvalidOperationException
    + FullyQualifiedErrorId : Amazon.S3.AmazonS3Exception,Amazon.PowerShell.Cmdlets.S3.GetS3BucketCmdlet

One of the security best practices for AWS is to not use your root account for general administration. So first you should create a new account in IAM and safely store the access key and secret key (we recommend KeePass if you don’t already have a secure password storage location).

Next, you can add the credentials to the SDK store on your computer using Set-AWSCredentials.

C:\Scripts> Set-AWSCredentials -AccessKey YOURACCESSKEY -SecretKey YOURSECRETKEY -StoreAs YOURPROFILENAME

The profile name you choose can be used later to specify different sets of credentials for different scenarios. For example, you may have multiple credentials for each of your customers, or multiple credentials for your own AWS account that have different levels of access, such as a day to day account that is read-only and another account that has more powerful access to do adds/moves/changes.

For example, to list the available S3 buckets using credentials stored as “ReadOnly” you can run:

C:\Scripts> Get-S3Bucket -ProfileName ReadOnly

If you name the profile “default” those credentials will be used as the default profile for any AWS PowerShell cmdlet you run.

If you want to switch to a different default credential for a PowerShell session you can run Set-AWSCredentials and specify the profile name you want that session to use by default.

C:\Scripts> Set-AWSCredentials -ProfileName YOURPROFILENAME

Working with Regions

Most AWS PowerShell cmdlets require you to specify a region for the service you are managing. There are exceptions to this. Route 53 is a global service that does not require regions to be specified. S3 and SES will both use default regions.

PS C:\Scripts> Get-R53HostedZones

Id                     : /hostedzone/abc123
Name                   : domainname.com.
Config                 : Amazon.Route53.Model.HostedZoneConfig
ResourceRecordSetCount : 3

Since it is possible to have resources such as S3 buckets and EC2 instances in different regions you will need to either specify a default region for your PowerShell sessions, or specify a region when running each command to get the desired result.

A list of regions can be displayed by running Get-AWSRegion.

PS C:\Scripts> Get-AWSRegion | ft -auto

Region         Name                      IsShellDefault
------         ----                      --------------
us-east-1      US East (Virginia)                 False
us-west-1      US West (N. California)            False
us-west-2      US West (Oregon)                   False
eu-west-1      EU West (Ireland)                  False
eu-central-1   EU Central (Frankfurt)             False
ap-northeast-1 Asia Pacific (Tokyo)               False
ap-southeast-1 Asia Pacific (Singapore)           False
ap-southeast-2 Asia Pacific (Sydney)              False
sa-east-1      South America (Sao Paulo)          False

Use the -Region switch with commands to specify the region, for example:

PS C:\Scripts> Get-EC2Instance -Region us-east-1

PS C:\Scripts> Get-EC2Instance -Region ap-southeast-2

Summary

As you can see there is a small amount of setup and familiarization required for the Amazon Web Services Tools for PowerShell. However once you are setup and running it becomes a lot quicker to launch a PowerShell session and start performing your administrative tasks.

In upcoming blog posts we’ll explore some of the common uses of PowerShell for managing Amazon Web Services.