How to run a speculative plan using the API workflow

Introduction

Using Terraform Enterprise (TFE)/ Terraform Cloud (TFC) you are able to create workspaces with an API-driven run workflow. This article describes how to create a speculative plan using this API-driven run. 

How To

• Create a workspace with an API driven workflow in your TFE/TFC environment

• Export these variables.

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

• Create a main.tf file with a null_resource that you will test with.

resource "null_resource" "test" {}

• Make a tar.gz file from the main.tf file.

tar -zcvf content.tar.gz main.tf

• Create a file called configuration_version_speculative.json with a configuration version. If you want normal runs remove the attribute section.

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

• Upload the configuration version.

For a better formatted output the example uses the open-source tool jq which can be found here.

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

• Save the upload-url from the output.
  • id -> configuration id is needed in later step.
  • upload-url -> url is needed for uploading the configuration in a later step.

    "id": "cv-w4i9xLmMCprKjFGp",
      "upload-url": "https://<TFE_HOSTNAME>/_archivist/v1/object/dmF1bHQ6djE6azNpUzQxZnRlTXNETDVmRGdXU1RIM2lreVowSUZkVzE0eW9wRmR2OC9SWGwzZ0NjWThhYlVoSTBKbFNnRytIVXp1M0krOHAzNGZnTzQ0Rk9wSDU3eHgrZGJOWUdrMFdxdThWMGJWczQxWFdPOXMxeHpYckRxVFJRUXdNZ0daVFJGYlhueUpJb2Q3dkY4eWY3TzVYRllrb2dtdnUveEhxTlRuRkg4M1lKRlptSkZYR3R0aWtDd3BlUHFWVG9qZXhWR1cyQVUvblB6T3pkcGZPUkxoNHJucnlwNkNWSkVoYVR3Z2ZydlJDbnV2bnFQTkc5UHRSSmtmTW9XeFNUZFZ5R1RQMEo2V0xqZHJJV0J6cmhqY0Erd0dDSisxZU9ieU1rZnF4N0NTR0pabm9zL3RJUThIY3BobXQ2bGhvazJGTTlsdXdFejNkUWFGSVhoNlRN"

• Upload the configuration. 

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

• Make a payload for the run as follows:

{
    "data": {
        "attributes": {
            "message": "speculative plan"
        },
        "type": "runs",
        "relationships": {
            "workspace": {
                "data": {
                    "type": "workspaces",
                    "id": "WORKSPACE_ID"
                }
            },
            "configuration-version": {
                "data": {
                    "type": "configuration-versions",
                    "id": "<CONFIGURATION_ID>"
                }
            }
        }
    }
}

• Make a manual run.

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

• In your browser, check the run with the run_id from the output of the previous.

      "links": {
        "self": "/api/v2/runs/run-rnkhSYviwYe2pFSH"

Results

The URL will look similar to this:

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

Additional Information

• If you want to resume normal runs, remove the attribute section in the configuration version and do the above steps again from the start.

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

• More information about the API-driven run workflow can be found here.