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:
The more easy installation of AWS Tools for PowerShell is to grab it directly from the PowerShell Gallery:
Install-Module AWSPowerShellIt’s quite a package so allow plenty of time for installation.
After installation you can check that the module is available locally:
To use the AWS module going forward you can import it with the following command:
Import-Module AWSPowerShellYou’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:
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 defaultTip! 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:
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:
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 Name | Region |
|---|---|
| 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-1Sample 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:
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:
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.largeYou 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,AverageThe output may look similar to this:
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!