How-to set a Workspace Terraform version using the API

Introduction

When creating a new workspace in HCP Terraform or Terraform Enterprise, you can specify a default Terraform version. Pinning a workspace's Terraform version ensures that your configurations run against a specific, supported version of Terraform Core. This practice is critical for maintaining stability and compatibility with your modules.

This guide demonstrates two methods for setting the Terraform version upon workspace creation.

Procedure

You can set the Terraform version for a workspace using two primary methods: the API or the tfe provider.

Option 1: Using the API

When using the Create a Workspace API endpoint, you can specify the desired Terraform version in the request payload using the data.attributes.terraform_version attribute. If you do not specify a version, the workspace defaults to the latest available version.

Here are two example payloads.

Payload 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"
  }
}

Payload 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"
  }
}

Option 2: Using the Terraform tfe Provider

When defining a workspace using the tfe_workspace resource from the tfe provider, you can use the terraform_version argument to set the workspace version within the resource block.

Example tfe_workspace resource configuration:

resource "tfe_workspace" "example" {
  name             = "my-workspace"
  organization     = "my-org"
  terraform_version = "1.0.0" ## Pin the desired version here
}

Additional Information

• For more details on the API payload, refer to the Create a Workspace API endpoint documentation.
• For more information on the tfe_workspace resource, see the official tfe_workspace resource documentation.