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 Manager

We’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-1

Querying 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
autoscaling

Querying 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
autoscaling

Querying 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-2

Querying 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          : 1

The 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.com

Easy!

As noted at the end of Jeff’s post, this data is available now and you can start using it today at no charge.