Querying Stacks from the Command-Line

In this final lab of the CloudFormation section, we’re going to look at how you can query stacks with the “describe-stack” command. With this command, we’ll show how you can access stack output values from within scripts, and how you can incorporate these queries into more powerful scripts that use the output values as arguments for other commands.

Using Resource Property Values

To begin, you might ask why you would need to know the values for AWS resource properties? The answer is that the applications that call your deployed code need these values to do things like construct endpoint URLs, apply security keys, or configure OAuth 2.0 authentication. To illustrate, let’s take a quick look at the tests in Postman, starting with the first test in the Admin_API collection. When you look at the URL for the request, you can see that it contains multiple variables that all need values:

In Postman, as we’re using it in this course, these values are assigned in Global variables, as shown below. Many of these values are parsed from test results at runtime, but some of them have to be obtained from the target environment in AWS.

Here’s another example of configuration that’s needed by Postman. The OAuth 2.0 app client settings shown below are needed to access the Customer API by authenticating with Cognito. Getting values for these settings requires stack queries, and sometimes stack queries combined with additional AWS commands:

Querying Stack Outputs

Our starting point for getting resource property values is the basic stack query. For this we use the “describe-stack” command that we’ve previously seen in the deploy.zsh script.

Step 1: Run the query-outputs.zsh script in the terminal

Looking in the folder that contains the sample scripts for CloudFormation, start by running the query-outputs.zsh script, which is shown below:

Because of the “—output table” argument on line 8, this command writes the stack outputs to the terminal in human-readable tabular format. When you run this script, you should get results that look something like this:

Step 2: Run the query-outputs.zsh script without the output argument

Next, remove line 8 from this script and run it again. You should now see the default JSON output format, as shown below. This is the machine-readable format to use when you need to reference elements from this output in your scripts.

Querying for Individual Stack Outputs

Now let’s look at the query-service.zsh script, starting with the first two commands on lines 5-13:

Both of these commands are assigning individual output values to variables for use further down in the script. They demonstrate the use of the “—query” argument for the “describe-stacks” command to select a named output element. So, in the query-outputs.zsh script we ran above, this argument didn’t name any specific outputs:

—query ‘Stacks\[0\].Outputs\[0\]’

The same argument in the query-service.zsh script specifies the “UserPoolDomainName” output:

—query “Stacks\[0\].Outputs\[?OutputKey=‘UserPoolDomainName’\].OutputValue”

Moving on to the third command, on lines 15-18, you can see how the Cognito userPoolId and userClientId values are obtained from the stack outputs. These are then used as arguments for the “cognito-idp describe-user-pool-client” command. This is an example of combining stack queries with other AWS commands, which we’ll get into further in a moment.

Step 3: Run the query-service.zsh script in the terminal

When you run this script, you should see JSON output showing all the properties for the specified Cognito User Pool Client, as shown below. Note that individual elements in JSON output like this can be subsequently referenced by other commands, as we’ll see next.

Combining Stack Queries with Other Commands

Now, let’s look at the third file in our CloudFormation samples folder: the query-attributes.zsh script:

This script demonstrates the use of stack queries that filter for individual output values, just like the previous script. Here, these values are then combined with other AWS commands to query for all the resource properties needed to test the APIs.

Let’s run through this step-by-step. The first command, on lines 5-8, queries the stack for the UserPoolDomainName property. This is needed as part of the OAuth 2.0 configuration in Postman, which you can see used on line 36, where the Cognito Auth URL is constructed.

The next two commands, on lines 10-18 are the same as we saw in the previous script. The variables assigned by these commands are used as arguments for the “aws cognito-idp describe-user-pool-client” command on lines 20-24. This command was called in the previous script, where it wrote the JSON output to the terminal. In this script, the result is filtered by the “—query” argument on line 23, to return the specific UserPoolClient.ClientSecret resource property.

The last two commands similarly combine a stack query with an additional AWS command. The stack query on lines 26-29 gets the value of the “AdminAPI” output. This value is then used in the query argument on line 32 of the “aws apigateway get-api-keys” command.

Step 4: Run the query-attributes.zsh script in the terminal

When you run this script, you should see results like this:

Note that to show how these scripts work, we’re just writing values to the terminal. But additional uses for scripts like this include generating client configuration files, as well as automating API testing. This latter use is something that we’ll demonstrate at the end of this course, in the section on CodePipeline.