How to run a speculative plan using the API workflow

Introduction

Workspaces in HCP Terraform or Terraform Enterprise can be configured with an API-driven run workflow. This workflow is ideal for integrations with CI/CD systems, allowing you to control runs programmatically. This guide details the procedure for triggering a speculative plan using the Runs API.

Prerequisites

Before you begin, you need the following:

• An existing workspace in HCP Terraform or Terraform Enterprise configured for an API-driven workflow.

  

• A team or user API token with permissions to execute runs on the workspace.
• The jq command-line tool installed to parse JSON responses. You can download it from the official jq website.

Procedure

Follow these steps to create and upload a configuration version and then trigger a speculative plan.

1. Set Environment Variables

Export the following variables in your shell to authenticate and target your requests. Replace the placeholder values with your specific information.

$ export TOKEN=<your_token>                      # permissions to execute runs on workspace
$ export TFE_HOST=<fqdn_tfe_host>                # FQDN of your TFE environment
$ export ORG_NAME=<your_organization_name>.      # Organization where the workspace resides
$ export WORKSPACE_NAME=<your_workspace_name>.   # Name of the workspace created 
$ export WORKSPACE_ID=<your_workspace_id>        # ID of the workspace created
$ export UPLOAD_FILE_NAME="./content.tar.gz".    # name of the zipfile that will be used in later steps

2. Create and Package a Terraform Configuration

First, create a simple main.tf file for testing.

resource "null_resource" "test" {}

Next, package this file into a compressed tarball named content.tar.gz.

$ tar -zcvf content.tar.gz main.tf

3. Create a Configuration Version

To initiate a speculative plan, you must first create a new configuration version with the speculative attribute set to true. Create a JSON file named configuration_version_speculative.json with the following content.

{
  "data": {
    "type": "configuration-versions",
    "attributes": {
      "speculative": true
    }
  }
}

Now, post this payload to the API to create the configuration version. This request returns an id for the new configuration version and a unique upload-url for the configuration content.

$ curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  --data @configuration_version_speculative.json \
  https://${TFE_HOSTNAME}/api/v2/workspaces/${WORKSPACE_ID}/configuration-versions | jq

From the JSON output, save the id (the configuration version ID) and the upload-url for the next steps.

{
  "data": {
    "id": "cv-w4i9xLmMCprKjFGp",
    "type": "configuration-versions",
    "attributes": {
      // ...
      "status": "pending",
      "upload-url": "https://<TFE_HOSTNAME>/_archivist/v1/object/..."
    }
  }
}

4. Upload the Configuration Content

Use the upload-url from the previous step to upload your content.tar.gz file.

$ curl \
  --header "Content-Type: application/octet-stream" \
  --request PUT \
  --data-binary @"./content.tar.gz" \
  "<PASTE_THE_UPLOAD_URL_HERE>"

5. Trigger the Speculative Plan

Finally, create a run payload to trigger the plan. Create a file named payload.json and populate it with your WORKSPACE_ID and the configuration version id you saved earlier.

{
  "data": {
    "attributes": {
      "message": "Speculative plan via API"
    },
    "type": "runs",
    "relationships": {
      "workspace": {
        "data": {
          "type": "workspaces",
          "id": "<PASTE_YOUR_WORKSPACE_ID_HERE>"
        }
      },
      "configuration-version": {
        "data": {
          "type": "configuration-versions",
          "id": "<PASTE_THE_CONFIGURATION_VERSION_ID_HERE>"
        }
      }
    }
  }
}

Send the request to the Runs API to start the speculative plan.

$ curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  --data @payload.json \
  https://${TFE_HOSTNAME}/api/v2/runs | jq '.'

Verification

The API response from the final step includes a run-id. You can use this ID to view the run in the HCP Terraform or Terraform Enterprise UI.

{
  "data": {
    "id": "run-rnkhSYviwYe2pFSH",
    // ...
  }
}

Navigate to the following URL in your browser, replacing the placeholders with your organization name, workspace name, and the run ID.

https://<TFE_HOSTNAME>/app/<ORGANIZATION_NAME>/workspaces/<WORKSPACE_NAME>/runs/<RUN_ID>

The UI will display the speculative plan, which confirms the process was successful.

Additional Information

• To resume normal, non-speculative runs, create a new configuration version without the speculative attribute in the payload. Then, repeat the procedure starting from step 3.

  {
    "data": {
      "type": "configuration-versions"
    }
  }

• For more details on the API-driven workflow, refer to the API-Driven Runs documentation.