More and more, Amazon Web Services has become a significant part of my day. Luckily for me, PowerShell and AWS, work well together. There’s long been the AWSPowerShell module, which much like the AWS CLI, allows us to issue API calls to AWS from a command line.
As a part of continuing my journey into AWS, and maintaining my mild obsession with PowerShell, I’ve decided to better learn a few PowerShell cmdlets, from the AWSPowerShell module throughout at least a couple of posts. As of version 3.3.365, the module only contains a few thousand cmdlets. It seems like AWS has gone ahead and made an investment here in PowerShell. Especially, when it wasn’t even terribly long ago that there were only 2,000.
(Get-Command -Module AWSPowershell | Measure-Object).Count 4499
Oh yeah, that reminds me, Lambda supports PowerShell (Core) now, too. As I read somewhere recently, “It’s not Bash, it’s not Ruby. It’s PowerShell.”
In a few previous, AWS-specific posts I was able to point out some things I thought should be changed. And somehow, AWS paid close enough attention, that some changes were actually made. It’s still hard to believe; it’s a bit surreal.
Hashtag AWS Tweet Prompts Fix to AWSPowerShell Module
AWS Stop-EC2Instance Needs Complimentary Cmdlet
More AWS PowerShell Changes Due to Twitter (and Me)
I’m mostly writing this evening to help solidify a few commands for my own education, and anyone else who is reading along. But… as I experimented with some of these AWS PowerShell cmdlets, I couldn’t help but feel that some changes were in order. So, with that knowledge, let’s review a few Region-specific cmdlets and touch on some potential changes, as they make the most sense to me.
Get-AWSRegion: “Returns the set of available AWS regions.”
When the Get-AWSRegion cmdlet is invoked, it returns the Region Name (the full name), the Region (abbreviated Region Name), and whether or not the Region is the default in the shell. In this first example, you can see that the default output returns all the Regions.
Get-AWSRegion Region Name IsShellDefault ------ ---- -------------- ap-northeast-1 Asia Pacific (Tokyo) False ap-northeast-2 Asia Pacific (Seoul) False ap-south-1 Asia Pacific (Mumbai) False ap-southeast-1 Asia Pacific (Singapore) False ap-southeast-2 Asia Pacific (Sydney) False ca-central-1 Canada (Central) False eu-central-1 EU Central (Frankfurt) False eu-west-1 EU West (Ireland) False eu-west-2 EU West (London) False eu-west-3 EU West (Paris) False sa-east-1 South America (Sao Paulo) False us-east-1 US East (Virginia) False us-east-2 US East (Ohio) False us-west-1 US West (N. California) False us-west-2 US West (Oregon) False
Wrong. Be sure to take a look at the examples further below. As you’ll see there are a couple of parameters—IncludeChina and IncludeGovCloud—that add some Regions that aren’t there by default. I’m not suggesting a change here, mostly, but Get-AWSRegion should return all the Regions, right?
Based on the cmdlet name alone, I suspected that all Regions were going to be listed in the output that’s returned. Good thing I looked into this cmdlet’s parameters, instead of assuming that the Regions were actually all included. And why China? I get why we might make an exception for GovCloud—we shouldn’t—but what was the thought in regard to China? You’ll see what I mean in the following examples.
(Get-AWSRegion | Measure-Object).Count 15 (Get-AWSRegion -IncludeChina | Measure-Object).Count 17 (Get-AWSRegion -IncludeChina -IncludeGovCloud | Measure-Object).Count 18
Now, let’s take a look at the SystemName parameter included in Get-AWSRegion. This is where it becomes quickly evident to me that we can definitely do better. Why does the Region property use a parameter called SystemName? I think maybe that parameter needs a Region parameter alias, at minimum.
Get-AWSRegion -SystemName us-west-1 Region Name IsShellDefault ------ ---- -------------- us-west-1 US West (N. California) False Get-AWSRegion -SystemName us-west-2 Region Name IsShellDefault ------ ---- -------------- us-west-2 US West (Oregon) False Get-AWSRegion -SystemName us-west-* Region Name IsShellDefault ------ ---- -------------- us-west-* Unknown False
I didn’t spend any time reading the help for Get-AWSRegion, but as you can see directly above, the wildcard character isn’t supported with the SystemName parameter. That’s too bad. That would’ve been a great addition to this cmdlet (and one that can still be added). To use a wildcard character against this value, you’re required to pipe your output to the Where-Object cmdlet and therefore, filter it further down the pipeline. Yes, this does mean that all results are piped to Where-Object, whereas a wildcard character built in to Get-AWSRegion, would filter immediately and avoid the need for the pipeline. The pipeline is crucial to the language, but when it’s not needed, we’re better off.
Get-AWSRegion | Where-Object Region -like 'us-west-*' Region Name IsShellDefault ------ ---- -------------- us-west-1 US West (N. California) False us-west-2 US West (Oregon) False
And if you’re wondering, Get-AWSRegion doesn’t include a Name parameter, so there’s no checking there for the ability to use wildcards.
Get-DefaultAWSRegion: “Returns the current default AWS region for this shell, if any, as held in the shell variable $StoredAWSRegion.”
This command’s purpose, as indicated, returns the Region the AWSPowerShell module’s commands should use by default. If the command returns nothing, then a default hasn’t been set. If it does, then someone has likely already used the command we’ll discuss after Get-DefaultAWSRegion: Set-DefaultAWSRegion.
Get-DefaultAWSRegion # Nothing here yet...
Before we move on, the commands that include the string “Default” before “AWS,” should have instead maintained the same noun prefix as Get-AWSRegion. That’s right, each of these three cmdlets should’ve included the verb, the dash, and then the string AWS, before the remaining portion of the included nouns. Why in the world would we stuff “AWS” into the middle of some command names and at the beginning of others? Amazon should have maintained a consistent prefix. Every Microsoft Active Directory command uses an AD prefix, right after the dash. You’ll never find it anywhere else. Even in the office, the prefix we use on our self-written functions is right where we’ve been trained to expect it:
<ApprovedVerb>-<Dept><SingularNoun(s)InCamelCase>
In my experience, AWS isn’t afraid of using command aliases—so one command can resolve to another—discontinuing the use of parameter names at times, and changing cmdlet names altogether. Therefore, I suspect someone needs to revisit these three. It’s not like Get-AWSRegionDefault, Set-AWSRegionDefault, and Clear-AWSRegionDefault don’t make sense and are already being used. The current commands should be aliases to these three, keeping the prefixes in the proper place.
Get-DefaultAWSRegion -> Get-AWSRegionDefault Set-DefaultAWSRegion -> Set-AWSRegionDefault Clear-DefaultAWSRegion -> Clear-AWSRegionDefault
While we’re here, we need to stop using the plural form of any nouns. That said, I do recognize this move is happening, such that Get-AWSCredentials is an alias that resolves to Get-AWSCredential. Oh look at that, the AWS prefix is in the right place on those two!
Set-DefaultAWSRegion: “Sets a default AWS region system name (e.g. us-west-2, eu-west-1 etc) into the shell variable $StoredAWSRegion. AWS cmdlets will use the value of this variable to satisfy their -Region parameter if the parameter is not specified.”
The first thing to notice here is that we have a Region parameter. That’s what Get-AWSRegion should’ve been included (in addition to SystemName [as not to create a breaking change]). Maybe make Region the actual parameter, and SystemName an alias to the Region parameter. That sounds like the best way to phase out that parameter.
Set-DefaultAWSRegion -Region ca-central-1 Get-DefaultAWSRegion Region Name IsShellDefault ------ ---- -------------- ca-central-1 Canada (Central) True
Clear-DefaultAWSRegion: “Clears any default AWS region set in the shell variable $StoredAWSRegion.”
Get-DefaultAWSRegion
Region Name IsShellDefault ------ ---- -------------- ca-central-1 Canada (Central) True
Clear-DefaultAWSRegion Get-DefaultAWSRegion # Nothing here again.
This evening we covered some Region cmdlets from the AWSPowerShell module. They all do what they should in the end, but in my mind, there’s some room for some changes for consistency’s sake and overall improvement. Perhaps we’ll do this again… there are some credential-related AWS cmdlets I’m going to need to learn once. and. for. all.
