Introduction
Terraform outputs are specific values from a Terraform run that are highlighted for easy access after a run completes. This guide outlines two options for extracting outputs from a run performed in HCP Terraform.
Procedure
Option 1: Use the Terraform CLI with the remote backend
This option requires configuring the HCP Terraform cloud integration (formerly remote backend) in your Terraform configuration.
Once you have configured the integration, retrieve the latest run's outputs by running the following command.
$ terraform output
A key advantage of this method is the ability to format the output as JSON. To render outputs as JSON, pass the -json flag to the command. You can find more details in the Terraform CLI output command documentation.
Option 2: Use the HCP Terraform API
If using the Terraform CLI locally is not suitable, you can retrieve run outputs using the HCP Terraform API.
Note: For Terraform Enterprise users, replace app.terraform.io with your instance's hostname in all API calls.
The process involves two main stages: retrieving the output ID (prefixed with wsout-) and then using that ID to retrieve its value.
Step 1: Retrieve Output IDs
You can retrieve output IDs from either the most recent state version or a specific historical state version.
Method A: From the most recent state version
To get outputs from the most recent state version in a workspace, use the Fetch the Current State Version for a Workspace API endpoint. You must include the outputsquery parameter to include the outputs in the response.
First, find the workspace ID by navigating to your workspace in the HCP Terraform UI and selecting Settings > General. The ID is at the top of the page and has the format ws-xxxxxxxxxxxxxxxx.
Use the workspace ID in the following API call.
$ curl \ --header "Authorization: Bearer $TOKEN" \ --header "Content-Type: application/vnd.api+json" \ "https://app.terraform.io/api/v2/workspaces/$WORKSPACE_ID/current-state-version?include=outputs"
The response includes each workspace output as an object within the .included array.
Method B: From a specific state version
To retrieve outputs from an older run, you must first identify its state version ID.
Navigate to the workspace, select the States tab, and choose the desired state version from the list. Copy the state version ID, which has the format sv-xxxxxxxxxxxxxxxx. Alternatively, you can use the List State Versions for a Workspace API endpoint.
Next, use the Show a State Version API endpoint with the outputsinclude query parameter to retrieve the outputs for that specific state version.
$ curl \ --header "Authorization: Bearer $TOKEN" \ --header "Content-Type: application/vnd.api+json" \ "https://app.terraform.io/api/v2/state-versions/$STATE_VERSION?include=outputs"
The response includes each workspace output as an object within the .included array.
Step 2: Retrieve the output value
After retrieving the output IDs using one of the methods above, use the Show a State Version Output API endpoint to get the value for each output.
$ curl \ --header "Authorization: Bearer $TOKEN" \ https://app.terraform.io/api/v2/state-version-outputs/$OUTPUT_ID
The data.attributes object in the response contains the output's name, type, value, and sensitivity status.