How-To
Working With AWS Regions in Windows PowerShell
Brien Posey explains how to address problems caused when your EC2 instances happen to be in a different region from the one that AWS Tools for PowerShell is configured to use.
Earlier I wrote about using Windows PowerShell to manage EC2 instances. Recently, someone told me they tried to use the Get-EC2Instance cmdlet to retrieve a list of their EC2 instances, but the cmdlet did not return any results.
One of the main things that can cause this problem is a regional mismatch. When you create an EC2 instance, that instance is created in a specific region. Similarly, AWS Tools for PowerShell is also linked to a particular region. If your EC2 instances happen to be in a different region from the one that AWS Tools for PowerShell is configured to use, then the Get-EC2Instance cmdlet will not display any results.
There are a couple of ways to determine the region AWS Tools for PowerShell is using by default. The easiest method is probably to enter the Get-AWSRegion cmdlet. Upon entering this cmdlet, AWS will display a list of all the AWS regions and will indicate (by way of a True/False statement) whether each is the default. If you look at Figure 1 for example, you can see that US East (Virginia) is the default region, because it is the only region for which the IsShellDefault attribute is set to True.
[Click on image for larger view.]Figure 1: US East Virginia is the default region.
If you want to be able to see the result a bit more easily, then you can filter PowerShell's output so that only the default region is displayed. The command used for doing so is:
Get-AWSRegion | Where IsShellDefault -EQ $True
You can see what this looks like in
Figure 2.
[Click on image for larger view.]Figure 2: PowerShell displays the default region.
So if you confirm your EC2 instances are in a different region from the one PowerShell is using by default, how can you switch to the correct region?
There are two different approaches to dealing with a PowerShell session mapped to an incorrect region. The method you should use to correct the problem depends largely on your own unique situation. If for example, most of your EC2 resources are in a different region from the one PowerShell is mapped to by default, then the best option is likely to map PowerShell to a different default region. If on the other hand, the default region aligns with some of your EC2 resources, but you need to access an instance in another region, then your best option is probably going to be to manually specify that instance's region. I will show you both techniques.
Manually Specifying a Region
Manually specifying a region is usually just a matter of appending the Region parameter to the cmdlet that you are using, and then specifying the region name. The trick however, is to remember that regions must be provided in a specific format. It is also important to remember that regions and availability zones are two different things.
To show you what I mean, take a look at Figure 3. This figure shows the EC2 dashboard. The region is listed as Oregon. However, PowerShell will not let you enter Oregon as the region name. The region name that you specify must match one of the regions listed in Figure 1.
[Click on image for larger view.]Figure 3: The EC2 Dashboard lists the region as Oregon.
It's also worth noticing that the instance shown in Figure 3 is running in an availability zone named US-West-2C. US-West-2C is an availability zone, not a region. The region that corresponds to this availability zone is US-West-2 (not 2C).
So with that said, check out Figure 4. Initially, I entered the Get-EC2Instance cmdlet by itself. No results were returned, because there are no instances in the default region. I then repeated the command, but this time entered US-West-2 as the region. This time a result was returned.
[Click on image for larger view.]Figure 4: This is how you specify a region.
Changing the Default Region
If you decide that you need to change the default region, you can do so by using the Set-DefaultAWSRegion cmdlet. You will simply need to append the Region parameter, followed by the name of the region that you want to use as the new default. To change the default region to US-West-2 for example, you would use this command:
Set-DefaultAWSRegion -Region US-West-2
You can see an example of how this process works in Figure 5.
[Click on image for larger view.]Figure 5: This is how you change the default region.
About the Author
Brien Posey is a 22-time Microsoft MVP with decades of IT experience. As a freelance writer, Posey has written thousands of articles and contributed to several dozen books on a wide variety of IT topics. Prior to going freelance, Posey was a CIO for a national chain of hospitals and health care facilities. He has also served as a network administrator for some of the country's largest insurance companies and for the Department of Defense at Fort Knox. In addition to his continued work in IT, Posey has spent the last several years actively training as a commercial scientist-astronaut candidate in preparation to fly on a mission to study polar mesospheric clouds from space. You can follow his spaceflight training on his Web site.