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.
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
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
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
As noted at the end of Jeff’s post, this data is available now and you can start using it today at no charge.