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

Introduction

For Terraform Enterprise versions predating v202209-1 (release sequence 654), the "plan-only" attribute for API triggered runs is unsupported and only a feature available within Terraform Cloud. For more information on the runs API, refer to the documentation linked at the end of the article.

Use Case

There are many instances where API driven workflow is preferred using Terraform Enterprise. In cases where a speculative plan is desired for validation of changes to infrastructure, and the "plan-only" attribute is not available, a simple workaround exists (outlined as follows):

Procedure

• Specify a configuration version payload and create a configuration version, saving the response:

  configuration_version_speculative.json

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

  request example

  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/your_workspace_id/configuration-versions

   

• Save the response upload-url and id
  
  

• Upload the compressed tarball containing relevant terraform code:

  curl \
  -- header "Content-Type: application/octet-stream" \
  --request PUT \
  --data-binary @"your_file.tar.gz"
  "upload_url_from_previous_step"

• Create an associated payload for the run (referred to in the following step as payload.json):
  
  

• {
  "data": {
  "attributes": {
  "message": "speculative plan"
  },
  "type": "runs",
  "relationships": {
  "workspace": {
  "data": {
  "type": "workspaces",
  "id": "your_workspace_id"
  }
  },
  "configuration-version": {
  "data": {
  "type": "configuration-versions",
  "id": "id_from_the_configuration_version"
  }
  }
  }
  }
  }

• Trigger a run using the above payload:
  

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

Additional Information

• Terraform Enterprise/Cloud Runs API: https://developer.hashicorp.com/terraform/cloud-docs/run/remote-operations#speculative-plans