How-to create a new workspace using the backend.tf

Expected Outcome

This guide explains how to create a new workspace in a Terraform Enterprise or HCP Terraform organization using the HCP Terraform cloud integration in your configuration file.

Prerequisites

• An existing organization in HCP Terraform or Terraform Enterprise.
• An API token with the appropriate permissions to create a workspace. The required Access Level depends on the token type:
  • Organization tokens: Implicit access is sufficient.
  • User and Team tokens: Explicit access is required.

Procedure

1. Create a file named backend.tf in your local configuration directory with the following content. This block configures the HCP Terraform cloud integration.

   terraform {
     backend "cloud" {
       hostname     = "TFE_HOSTNAME_OR_app.terraform.io"
       organization = "ORGANIZATION_NAME"
   
       workspaces {
         name = "NEW_WORKSPACE_NAME"
       }
     }
   }

   Note: Replace the placeholder values.

   • hostname: For HCP Terraform, use app.terraform.io. For Terraform Enterprise, use your instance's hostname.
   • organization: The name of your existing organization.
   • name: The name of the new workspace you want to create.

2. In your terminal, navigate to the directory containing your backend.tf file and log in to HCP Terraform or Terraform Enterprise.

   $ terraform login

3. Follow the prompts to provide your API token when requested.

4. Initialize the Terraform configuration. This command reads the backend block, connects to your organization, and creates the new workspace.

   $ terraform init

Verification

After running terraform init, you can confirm that the workspace was created successfully.

1. Check the UI:
   • Terraform Enterprise: Navigate to https://<TFE_HOSTNAME>/app/<ORGANIZATION_NAME>/workspaces
   • HCP Terraform: Navigate to https://app.terraform.io/app/<ORGANIZATION_NAME>/workspaces
2. Use the API:
   • You can also use the API to List workspaces and verify the new workspace is present.