How to get an execution plan with a remote backend

Avatar
Mallika Tadiparthi
  • Updated

Introduction

This guide explains how to download a run's execution plan in JSON format from HCP Terraform or Terraform Enterprise using the API. You can use the Plans API to retrieve this information.

Expected Outcome

You will successfully download the JSON execution plan for a specific run.

Prerequisites

  • A workspace configured with a remote backend in HCP Terraform or Terraform Enterprise.
  • An API token with admin permissions for the target workspace.

Procedure

Follow these steps to retrieve the execution plan.

Replace the following placeholder values in the example commands:

  • <HOSTNAME>: Your Terraform Enterprise hostname or app.terraform.io for HCP Terraform.
  • <TOKEN>: Your API token.
  • <RUN_ID>: The ID of the target run.
  • <PLAN_ID>: The ID of the plan, retrieved in step 2.

  1. Find the Run ID

    Locate the run-id from the Run Details page for the desired run in the HCP Terraform or Terraform Enterprise UI. The ID is prefixed with run-.

  2. Retrieve the Plan ID

    Use the Runs API to get the details for your run, which includes the plan-id.

    $ curl \
    --header "Authorization: Bearer <TOKEN>" \
    https://<HOSTNAME>/api/v2/runs/<RUN_ID>

    The JSON response body contains the plan-id.

    ##...
    "plan": {
      "data": {
        "id": "plan-YYYYYYYYYYYYYYYY",
        "type": "plans"
      }
    },
##...

  3. Download the JSON Execution Plan

    Using the plan-id from the previous step, call the Plans API endpoint for the JSON execution plan.

    $ curl \
    --header "Authorization: Bearer <TOKEN>" \
    --header "Content-Type: application/vnd.api+json" \
    --location https://<HOSTNAME>/api/v2/plans/<PLAN_ID>/json-output

Warning: The JSON plan contains potentially sensitive information, including the values of sensitive variables and copies of the prior and post-refresh state. Access to this endpoint requires elevated permissions.

Additional Information

Articles in this section

See more

Related articles