AWS – PowerShell

AWS Tools for PowerShell introduction

This article will connect the two dots named “AWS” and “PowerShell”. In five to ten minutes you will know exactly how you connect to AWS and manage services using PowerShell.

The topics are:

  • How to install the AWS PowerShell module
  • How to authenticate your PowerShell session with AWS
  • Configuring the target region of your AWS PowerShell scripts
  • Running a few sample PowerShell scripts for AWS

Let’s go!

Installing the AWS PowerShell Module

The AWS PowerShell module is available as a standalone download from here: https://aws.amazon.com/powershell/. Since the download includes the entire AWS API package of which AWS Tools for PowerShell is just a subcomponent, I don’t recommend installing this:

AWS API package installation

 

The more easy installation of AWS Tools for PowerShell is to grab it directly from the PowerShell Gallery:

Install-Module AWSPowerShell

It’s quite a package so allow plenty of time for installation.

After installation you can check that the module is available locally:

PS C:\Skrubbeltrang > Get-Module -ListAvailable *AWS*

Directory: C:\Program Files\WindowsPowerShell\Modules

ModuleType Version    Name                                ExportedCommands

---------- -------    ----                                ----------------

Binary     3.3.522.0  AWSPowerShell                       {Clear-AWSHistory, Set-AWSHistoryConfiguration, Initialize-AWSDefaultConfiguration, Clear-AWSDefaultConfiguration...}

To use the AWS module going forward you can import it with the following command:

Import-Module AWSPowerShell

You’re now ready to start firing off AWS commands in PowerShell.

Connecting to AWS With PowerShell

To get programmatic access to AWS you need to authenticate with Access Keys. The AWS access keys consist of two parts: An access key ID and a secret access key. You can generate them in the AWS console by following these steps:

Start by logging in to the IAM Console and select My Security Credentials:

AWS IAM Console set up Access Keys for PowerShell

Expand Access Keys and generate a new access key:

Make sure to grab both parts of the AWS access key: The access key ID and the secret access key. You will not be able to access it again when the dialog box is closed!

You can now use the access key ID and secret access key to establish a profile on your local machine using the Set-AWSCredential command:

Set-AWSCredential -AccessKey AKIAITRASVDO2JZFXHJA -SecretKey WdQ+2C7N0RZABzHVEgz4dxibxNLfzEaqi6C6VKZD -StoreAS default

Tip! If you store the profile with the name “default” your AWS PowerShell session will automatically use this profile if no other profile is specified.

After setting up the profile you can review it with the Get-AWSCredential command:

PS C:\Skrubbeltrang> Get-AWSCredential -ListProfileDetail

ProfileName StoreTypeName         ProfileLocation
----------- -------------         ---------------
default     NetSDKCredentialsFile

All AWS commands will now authenticate with the default credentials unless you specify an explicit profile using the ProfileName parameter.

You can activate another profile in the current session using the Set-AWSCredential command but for most simple setups, using the default profile implicitly will work just fine.

Profile credentials are stored in AppData\Local\AWSToolkit\RegisteredAccounts.json. The credentials are protected by the Windows Data Protection API (DPAPI), which means they are protected by the credentials of the Windows user and locked to the current machine (on which the Windows user profile resides). This has two important consequences – understand and remember this to save a lot of troubleshooting when scheduling AWS tasks:

  • You must generate the AWS profile with the same Windows account that will run it (to schedule a job as a service you MUST log in as the service account on the scheduling server to generate the AWS profile)
  • You can’t copy the credentials to a new machine (to move the script to a new machine you must generate a new profile on the new machine)

Configuring Your Target Region

The final step before we can start scripting is to configure the proper target region.

AWS Tools for PowerShell must know what region to target in order to avoid the following error message:

Get-EC2Instance : No region specified or obtained from persisted/shell defaults.
At line:1 char:1
+ Get-EC2Instance
+ ~~~~~~~~~~~~~~~
    + CategoryInfo          : InvalidOperation: (Amazon.PowerShe...2InstanceCmdlet:GetEC2InstanceCmdlet)
	[Get-EC2Instance], InvalidOperationException
    + FullyQualifiedErrorId : InvalidOperationException,Amazon.PowerShell.Cmdlets.EC2.GetEC2InstanceCmdlet

The target region of the session can be set for individual commands using the Region parameter.

Tip! If you have most resources set up in the same region you can set the default region using the Set-DefaultRegion command.

The region must be set to one of the values in the second column:

AWS API Regions

Region NameRegion
US East (Ohio)us-east-2
US East (N. Virginia)us-east-1
US West (N. California)us-west-1
US West (Oregon)us-west-2
Asia Pacific (Hong Kong)ap-east-1
Asia Pacific (Mumbai)ap-south-1
Asia Pacific (Seoul)ap-northeast-2
Asia Pacific (Singapore)ap-southeast-1
Asia Pacific (Sydney)ap-southeast-2
Asia Pacific (Tokyo)ap-northeast-1
Canada (Central)ca-central-1
China (Beijing)cn-north-1
China (Ningxia)cn-northwest-1
EU (Frankfurt)eu-central-1
EU (Ireland)eu-west-1
EU (London)eu-west-2
EU (Paris)eu-west-3
EU (Stockholm)eu-north-1
South America (São Paulo)sa-east-1
AWS GovCloud (US-East)us-gov-east-1
AWS GovCloud (US)us-gov-west-1

To set your default region to Frankfurt use the following command: 

Set-DefaultAWSRegion eu-central-1

Sample AWS PowerShell Scripts

With the AWS Tools for PowerShell in place, a successful connection to AWS and the default region configured, let’s do some actual work.

The following scripts assume you have completed the steps in the previous sections.

List Virtual Machines Using PowerShell

Get-EC2Instance is the command to get some information about your EC2 instances. Each EC2 instance object has an Instances property which has various details on your VM:

PS C:\Skrubbeltrang> Get-EC2Instance | % { $_.Instances }

InstanceId          InstanceType Platform PrivateIpAddress PublicIpAddress SecurityGroups           SubnetId        VpcId
----------          ------------ -------- ---------------- --------------- --------------           --------        -----
i-0890b237aef43fe98 t2.medium    Windows  172.31.24.41                     {launch-wizard-5}        subnet-658e141e vpc-dd677ab4
i-01093ec32631a7be4 t2.micro     Windows  172.31.24.43                     {Lab, RDP + Debug}       subnet-658e141e vpc-dd677ab4
i-04cb999d8be5e7009 t2.medium    Windows  172.31.24.45                     {Lab, RDP + Debug}       subnet-658e141e vpc-dd677ab4
i-0b5d9c29a93907b19 t2.medium    Windows  172.31.24.47                     {Lab, RDP + Debug}       subnet-658e141e vpc-dd677ab4

You may notice one important piece of information missing. To get the EC2 instance name, which is embedded in a Name Tag, use the following lines of code:

Get-EC2Instance | Select-Object -ExpandProperty Instances | ForEach-Object {
  $Name = (Get-EC2Instance $_.InstanceID | Select-Object -ExpandProperty Instances | Select-Object Tag).Tag
  Write-Host $_.InstanceID `t $Name.Value
}

These lines will generate output similar to the following, where you see the InstanceID to name tag reference:

i-0890b237aef43fe98      ManagementServer
i-01093ec32631a7be4      Window 2008 R2
i-04cb999d8be5e7009      TokenSnatcher_Test
i-0b5d9c29a93907b19      E365M_DC

Start and Stop Virtual Machines Using PowerShell

To  start one of your EC2 instances use the Start-EC2Instance command and provide the InstanceID of the EC2 instance:

Start-EC2Instance 'i-0b5d9c29a93907b19'

To stop the same instance use the Stop-EC2Instance command:

Stop-EC2Instance 'i-0b5d9c29a93907b19'

Tip! Use tags intelligently on your AWS resources in order to support targeting objects easily with your PowerShell scripts.

Change EC2 Instance Type Using PowerShell

To change the hardware size of your virtual machines you must change the InstanceType attribute of the EC2 instance.

This can be done with the following command:

Edit-EC2InstanceAttribute -InstanceId "i-0b5d9c29a93907b19" -Attribute "instanceType" -Value t2.large

You can find a list of available instance types here.

Monitor and Analyze AWS Performance and Utilization Metrics Using PowerShell

The performance of your AWS infrastructure is constantly logged and data points are available via the CloudWatch service. Performance metrics have the following retention:

  • 1 minute data points are available for 15 days
  • 5 minute data points are available for 63 days
  • 1 hour data points are avaiable for 455 days

To retrieve data points from CloudWatch use the command Get-CWMetricStatistics. It has quite a few parameters that states the service, metric, instance, time frame, sample interval, statistical information type and more.

The following script will show you the CPU maximum and average utilization percentage for a given EC2 instance during the last week with a one hour sample interval:

$EndDate = Get-Date
$StartDate = $EndDate.AddDays(-7)
$Data = Get-CWMetricStatistics -Namespace "AWS/EC2" -MetricName "CPUUtilization" -Dimension @{"Name"="InstanceId";"Value"="i-0b5d9c29a93907b19"}  -UtcStartTime $StartDate -UtcEndTime $EndDate -Period 3600 -Statistic @("Maximum","Average")
$Data.Datapoints | Sort-Object TimeStamp | ft TimeStamp,Maximum,Average

The output may look similar to this:

Timestamp                      Maximum          Average
---------                      -------          -------
6/18/2019 9:25:00 PM  25.5833333333339 6.16080740020377
6/18/2019 10:25:00 PM 20.7499999999997 6.10591329381619
6/18/2019 11:25:00 PM 19.9166666666664 6.13058102559353
6/19/2019 12:25:00 AM 21.3333333333336 6.17326186286314
6/19/2019 1:25:00 AM   20.916666666667 6.24051318267419
6/19/2019 2:25:00 AM  21.2711864406783 6.28474653453121
6/19/2019 3:25:00 AM  21.3114754098361 6.20924137877804
6/19/2019 4:25:00 AM  34.2500000000003 7.36355198975024
6/19/2019 5:25:00 AM  15.8333333333333 5.50554050507857
6/19/2019 6:25:00 AM  15.9166666666685 5.61130445185392
6/19/2019 7:25:00 AM  15.7500000000012 5.59249444290078
6/19/2019 8:25:00 AM  15.9322033898299  5.5448249513754
6/19/2019 9:25:00 AM  16.1666666666648 5.58090750517117
6/19/2019 10:25:00 AM 15.8333333333333 5.60937220215495
6/19/2019 11:25:00 AM 16.2711864406755 5.63883138834862
6/19/2019 12:25:00 PM 15.7377049180334 5.67969883609644
6/19/2019 1:25:00 PM  16.0833333333327 5.66284731869962
6/19/2019 2:25:00 PM  16.0833333333327 5.72660577012132
6/19/2019 3:25:00 PM  16.4166666666673 5.90379812293539
6/19/2019 4:25:00 PM  16.3559322033892 5.85187860825541
6/19/2019 5:25:00 PM  16.3559322033892 5.87568884875428
6/19/2019 6:25:00 PM  16.1475409836072 5.91534994288534
6/19/2019 7:25:00 PM  16.4999999999994 6.00194768608566
6/19/2019 8:25:00 PM  15.8196721311469 5.72859706399924
6/19/2019 9:25:00 PM  16.0000000000006 5.64684750393632
6/19/2019 10:25:00 PM 16.0000000000006 5.66860933592664
6/19/2019 11:25:00 PM 16.0833333333327 5.63785503689294
6/20/2019 12:25:00 AM 16.6949152542379 5.84837802167267
6/20/2019 1:25:00 AM  16.0833333333327 5.82561166682107
6/20/2019 2:25:00 AM             16.25 5.86659527337838
6/20/2019 3:25:00 AM  16.7796610169485  6.0002469821864
6/20/2019 4:25:00 AM   38.135593220339 7.15940268901859
6/20/2019 5:25:00 AM             16.25 5.92659959556663
6/20/2019 6:25:00 AM  16.0655737704906 5.95945015590751
...

Using PowerShell to fetch and process performance data from CloudWatch can help you get insights that are not available from the standard console.

Summary

I hope you feel that the dots got connected, or at least got a little bit closer. Managing AWS with PowerShell can save you a lot of time (and money).

Automating AWS with PowerShell can help you standardize the provisioning of new AWS resources, shut down servers during known idle periods, analyze performance to identify candidates for scaling up or down and much more.

With a good grip on AWS Tools for PowerShell nothing stands in your way but your lack of imagination!