Triggering speculative plans via API driven workflow in versions before 202209-1

Problem

In Terraform Enterprise versions before v202209-1, the Runs API does not support the plan-only attribute for runs triggered via the API. This attribute is available in HCP Terraform and later versions of Terraform Enterprise, allowing users to create a run that only plans and does not apply.

This article provides a workaround to trigger a speculative plan using the API for affected Terraform Enterprise versions.

Prerequisites

• A Terraform Enterprise instance running a version prior to v202209-1.
• A user or team API token with permissions to manage runs and configuration versions for the target workspace.
• The ID of the target workspace (e.g., ws-xxxxxxxxxxxx).
• Your Terraform configuration, packaged as a .tar.gz file.

Procedure

This workaround involves creating a speculative configuration version first and then creating a run associated with it. This process effectively results in a plan-only operation.

1. Create a Speculative Configuration Version

First, make a request to the API to create a new configuration version with the speculative attribute set to true. This tells Terraform Enterprise that the configuration is for planning purposes only.

$ curl \
  --header "Authorization: Bearer <YOUR_API_TOKEN>" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  --data '{"data": {"type": "configuration-versions","attributes": {"speculative": true}}}' \
  https://<TFE_HOSTNAME>/api/v2/workspaces/<YOUR_WORKSPACE_ID>/configuration-versions

From the JSON response, save the id of the new configuration version and the upload-url. You will need these for the next steps.

2. Upload the Configuration Archive

Next, upload your compressed Terraform configuration (.tar.gz) to the upload-url you received in the previous step.

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

3. Trigger the Run

Finally, create a new run and associate it with the speculative configuration version you created in Step 1. This will trigger a speculative plan in the workspace.

Create a JSON payload for the run, referencing your workspace ID and the configuration version ID.

run-payload.json

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

Use this payload to trigger the run.

$ curl \
  --header "Authorization: Bearer <YOUR_API_TOKEN>" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  --data @run-payload.json \
  https://<TFE_HOSTNAME>/api/v2/runs

Outcome

After completing these steps, a new run will start in your Terraform Enterprise workspace. Because it uses a speculative configuration version, this run will only perform a plan and will not be confirmable or applyable, achieving the goal of a plan-only API-driven workflow.

Additional Information

For more details on API-driven runs, refer to the Remote Operations API documentation.