AWS Developer Tools Blog
AWS Regions and Windows PowerShell
The majority of the cmdlets in the AWS Tools for Windows PowerShell require that you specify an AWS region. Specifying a region defines the service endpoint that is used for the request, in addition to scoping the resources you want to operate on. There are, however, a couple of exceptions to this rule:
- Some services are considered region-less. This means that the service exposes an endpoint that does not contain any region information, for example AWS Identity and Access Management (IAM) and Amazon Route 53 fall into this category.
- Some services expose only a single regional endpoint, usually in the US East (Northern Virginia) region. Examples for this category are Amazon Simple Email Service (SES) and AWS OpsWorks.
Cmdlets for services in these categories do not require that you specify a region and are designed, in the case of the second category, to automatically select the single regional endpoint for you. Note that although Amazon Simple Storage Service (S3) has multiple regional endpoints, its cmdlets can also operate without the need for an explicit region, falling back to the US East (Northern Virginia) region in this scenario. This may or may not work based on location constraints on your buckets. You therefore might want to consider always specifying a region anyway (this also safeguards against assumptions for services that may expand to other regions in the future).
This blog post describes how to specify the region for a cmdlet and how to specify a default region. A useful summary guide to endpoints and regions for services can be found at Regions and Endpoints in the Amazon Web Services General Reference.
Specifying the Region for a Cmdlet
All cmdlets that require region information to operate expose a -Region parameter. This parameter accepts a string value, which is the system name of the AWS region. For example, we can obtain a list of all running Amazon EC2 instances in the US West (Oregon) region as follows:
PS C:> Get-EC2Instance -Region us-west-2
Note:For simplicity, the cmdlet examples shown here assume that your AWS credential information is being obtained automatically, as described in Handling Credentials with AWS Tools for Windows PowerShell.
Similarly, we can obtain the set of Amazon Machine Images (AMIs) for Microsoft Windows Server 2012, this time in the EU (Ireland) region:
PS C:> Get-EC2ImageByName -Region eu-west-1 -Name "windows_2012_base"
Given these examples, you might write the following command to start an instance:
PS C:> Get-EC2ImageByName -Region eu-west-1 -Name "windows_2012_base" | New-EC2Instance -InstanceType m1.small -MinCount 1 -MaxCount 1
New-EC2Instance: The image id '[ami-a63edbd1]' does not exist
At line:1 char:66
+ Get-EC2ImageByName -Region eu-west-1 -Name "windows_2012_base"
| New-EC2Instance ...
+ ~~~~~~~~~~~~~~~
+ CategoryInfo : InvalidOperation: (Amazon.PowerShe...2InstanceCmdlet:NewEC2InstanceCmdlet) [New-EC2Instance], InvalidOperationException
+ FullyQualifiedErrorId : Amazon.EC2.AmazonEC2Exception,Amazon.PowerShell.Cmdlets.EC2.NewEC2InstanceCmdlet
Oops! As you can see, the -Region parameter is scoped to the individual cmdlet, so the AMI that is returned is specific to the EU (Ireland) region. The New-EC2Instance cmdlet also needs to use the EU (Ireland) region, otherwise the AMI will not be found, so we must supply a matching -Region parameter (or, as shown later, have this region be our shell default):
PS C:> Get-EC2ImageByName -Region eu-west-1 -Name "windows_2012_base" | New-EC2Instance -InstanceType m1.small -MinCount 1 -MaxCount 1 -Region eu-west-1
ReservationId : r-12345678
OwnerId : ############
RequesterId :
GroupId : {sg-abc12345}
GroupName : {default}
RunningInstance : {}
Specifying a Default Region
Adding an explicit -Region parameter to each cmdlet can become awkward for anything more than one or two commands, so I make use of a default region in my shell. To manage this, I make use of the region cmdlets in the toolset:
-
Set-DefaultAWSRegion -
Get-DefaultAWSRegion -
Get-AWSRegion -
Clear-DefaultAWSRegion
Set-DefaultAWSRegion accepts the (string) system name of an AWS region (similar to the -Region parameter on cmdlets) or an AWSRegion object, which can be obtained from Get-AWSRegion:
# set a default region of EU West (Ireland) for all subsequent cmdlets
PS C:> Set-DefaultAWSRegion eu-west-1
# query the set of AWS regions (to include AWS GovCloud, add the -IncludeGovCloud switch)
PS C:> Get-AWSRegion
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) True
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 list to set another default by selection:
PS C:> Get-AWSRegion |? { $_.Name.Contains("Tokyo") } | Set-DefaultAWSRegion
# test it!
PS C:> Get-DefaultAWSRegion
Region Name IsShellDefault
------ ---- --------------
ap-northeast-1 Asia Pacific (Tokyo) True
Clear-AWSDefaultRegion can be used to clear a default region. After you use this cmdlet you need to start using the -Region parameter with the service cmdlets again. In scripts that run a lot of service cmdlets, you may find it useful to use the Get-DefaultAWSRegion and Set-DefaultAWSRegion cmdlets at the start and end of the script, perhaps in conjunction with a region script parameter, to temporarily switch away from your regular shell default and restore the original default on exit.
By the way, setting a default region doesn’t preclude overriding this subsequently on a per-cmdlet basis. Simply add the -Region parameter as needed for the particular cmdlet invocation.