How-to set a Workspace Terraform version using the API

Introduction

When creating a new workspace there is a way to set the default Terraform version.

Use Case

Being able to pin a workspace terraform version upon creation will allow organization owners to control which Terraform core version their user's workspace will run against and ensure the modules are ran against the Terraform core version it currently supports.

There are a couple of alternatives using the API or CLI to create a workspace with a pinned terraform core version.

For API workspace creation you would stipulate the workspace terraform version within the data attribute data.attributes.terraform-version within the payload.json. 

Example:

data.attributes.terraform-version string (nothing) The version of Terraform to use for this workspace. Upon creating a workspace, the latest version is selected unless otherwise specified (e.g. "0.11.1").

Here are some sample payloads for the API:

Without a VCS repository

{
  "data": {
    "attributes": {
      "name": "workspace-1",
      "terraform_version": "<pin the version>",
      "resource-count": 0,
      "updated-at": "2017-11-29T19:18:09.976Z"
    },
    "type": "workspaces"
  }
}

With a VCS repository

{
  "data": {
    "attributes": {
      "name": "workspace-2",
      "resource-count": 0,
      "terraform_version": "<pin the version>",
      "working-directory": "",
      "vcs-repo": {
        "identifier": "example/terraform-test-proj",
        "oauth-token-id": "<oath-token>",
        "branch": ""
      },
      "updated-at": "2017-11-29T19:18:09.976Z"
    },
    "type": "workspaces"
  }
}

For the CLI option, the CLI create workspace resource argument terraform_version would be used to set the workspace version within the resource block. 

Example:

terraform_version - (Optional) The version of Terraform to use for this workspace. Defaults to the latest available version

Additional Information

• For additional assistance please contact HashiCorp Support to request additional assistance.