AWS Developer Tools Blog
Query Systems Manager Parameter Store for AWS Regions, endpoints and more using PowerShell
In Jeff Barr’s recent blog post, he announced support for querying AWS Region and service availability programmatically by using AWS Systems Manager Parameter Store. The examples in the blog post all used the AWS CLI, but the post noted that you can also use the AWS Tools for PowerShell.
In this post I’ll show you how to use the Systems Manager cmdlets in the AWS Tools for PowerShell to query the same data.
Prerequisites
To use the cmdlets shown in this blog post, you need to install the AWS Tools for Windows PowerShell module or the AWS Tools for PowerShell Core module (PowerShell Core is also known as PowerShell 6). You can use the PowerShell Core module if you’re using Windows, Linux, or macOS.
If you’re using Amazon EC2 Windows instances, the tools are preinstalled for you. Also, thanks to a change to adopt PowerShell Standard, you can now use the AWS Tools for PowerShell Core module if you’re running Windows PowerShell versions 3 through 5.x.
After it’s installed, import the relevant module (AWSPowerShell if using Windows PowerShell, or AWSPowerShell.NetCore if using PowerShell 6) and configure credentials. The user guide for the tools describes how to set up credential profiles to use with the tools.
AWS Systems Manager Cmdlets
The cmdlets for Systems Manager have the prefix “SSM” applied to the cmdlet names. You can obtain a full list of all cmdlets for the service by using the Get-AWSCmdletName cmdlet.
PS C:\> Get-AWSCmdletName -Service SSM
CmdletName ServiceOperation ServiceName
---------- ---------------- -----------
Add-SSMResourceTag AddTagsToResource AWS Systems Manager
Edit-SSMDocumentPermission ModifyDocumentPermission AWS Systems Manager
Get-SSMActivation DescribeActivations AWS Systems Manager
Get-SSMAssociation DescribeAssociation AWS Systems Manager
....
Write-SSMComplianceItem PutComplianceItems AWS Systems Manager
Write-SSMInventory PutInventory AWS Systems Manager
Write-SSMParameter PutParameter AWS Systems ManagerWe’ll work with two cmdlets in this blog post: Get-SSMParametersByPath, which returns all parameters sharing a common key path, and Get-SSMParameter, which returns a specific parameter.
Querying to find active AWS Regions
To query all active Regions, we use the parameter key path, /aws/service/global-infrastructure/regions, with the Get-SSMParametersByPath cmdlet.
PS C:\> Get-SSMParametersByPath -Path '/aws/service/global-infrastructure/regions'
ARN : arn:aws:ssm:us-west-2::parameter/aws/service/global-infrastructure/regions/ap-northeast-1
LastModifiedDate : 4/18/2019 2:05:37 AM
Name : /aws/service/global-infrastructure/regions/ap-northeast-1
Selector :
SourceResult :
Type : String
Value : ap-northeast-1
Version : 1
ARN : arn:aws:ssm:us-west-2::parameter/aws/service/global-infrastructure/regions/ap-northeast-2
LastModifiedDate : 4/18/2019 2:05:42 AM
Name : /aws/service/global-infrastructure/regions/ap-northeast-2
Selector :
SourceResult :
Type : String
Value : ap-northeast-2
Version : 1
...We get back a series of parameter objects, one per Region. We could send these objects to the pipeline to process, or filter them immediately to just the list of Regions, by using an expression like the following.
PS C:\> (Get-SSMParametersByPath -Path '/aws/service/global-infrastructure/regions').Value
ap-northeast-1
ap-northeast-2
ca-central-1
eu-north-1
eu-west-1
eu-west-2
sa-east-1
us-east-1
us-east-2
us-west-1
ap-northeast-3
ap-south-1
ap-southeast-1
ap-southeast-2
cn-north-1
cn-northwest-1
eu-central-1
eu-west-3
us-gov-east-1
us-west-2
us-gov-west-1Querying to find all services
To query services, we use a different key path: /aws/service/global-infrastructure/services. The following query displays a complete list of all available AWS services, sorted alphabetically. It also displays the first 10 (out of 155 at the time of this writing).
PS C:\> (Get-SSMParametersByPath -Path '/aws/service/global-infrastructure/services').Value |
sort |
select -first 10
acm
acm-pca
alexaforbusiness
apigateway
application-autoscaling
appmesh
appstream
appsync
athena
autoscalingQuerying services that are available in a Region
PS C:\> (Get-SSMParametersByPath -Path '/aws/service/global-infrastructure/regions/us-east-1/services').Value |
sort |
select -first 10
acm
acm-pca
alexaforbusiness
apigateway
application-autoscaling
appmesh
appstream
appsync
athena
autoscalingQuerying Regions for a service
Inverting the query, what if we want to know what Regions a given service supports? For example, in the following we want to know where Amazon Athena is currently available.
PS C:\> (Get-SSMParametersByPath -Path '/aws/service/global-infrastructure/services/athena/regions').Value
ap-northeast-1
ap-northeast-2
ap-south-1
ap-southeast-1
ap-southeast-2
ca-central-1
eu-central-1
eu-west-1
us-east-2
us-gov-west-1
eu-west-2
us-east-1
us-west-2Querying for a service name
To get the official name of a service you can run this query:
PS C:\> Get-SSMParametersByPath -Path '/aws/service/global-infrastructure/services/athena'
ARN : arn:aws:ssm:us-west-2::parameter/aws/service/global-infrastructure/services/athena/longName
LastModifiedDate : 4/18/2019 2:05:52 AM
Name : /aws/service/global-infrastructure/services/athena/longName
Selector :
SourceResult :
Type : String
Value : Amazon Athena
Version : 1The example shows that the value for the parameter contains the official service name.
Querying for a service’s regional endpoint
When using the cmdlets, most of the time you don’t need to worry about a service’s regional endpoint. This is because the tools form this up for you before making calls to an operation. If want to know the endpoint, however, you can query for it.
PS C:\> (Get-SSMParameter -Name '/aws/service/global-infrastructure/regions/us-west-1/services/s3/endpoint').Value
s3.us-west-1.amazonaws.comEasy!
As noted at the end of Jeff’s post, this data is available now and you can start using it today at no charge.