Selecting a workspace when running Terraform in automation

Problem

When running the Terraform CLI in an automation pipeline with multiple workspaces, the terraform init command may present an interactive prompt to select a workspace. This behavior can cause automation workflows to hang or fail because they cannot respond to the prompt.

The prompt appears as follows.

$ terraform init

Initializing the backend...

Successfully configured the backend "remote"! Terraform will automatically
use this backend unless the backend configuration changes.

The currently selected workspace (default) does not exist.
This is expected behavior when the selected workspace did not have an
existing non-empty state. Please enter a number to select a workspace:

1. aaa
2. bar
3. foo
4. zzz

Enter a value:

Solutions

To bypass the interactive prompt, you must pre-select the desired workspace. The following solutions describe how to configure the workspace selection for automation.

Solution 1: Use the TF_WORKSPACE Environment Variable

You can specify the target workspace by setting the TF_WORKSPACE environment variable. For more details, refer to the guide on Running Terraform in Automation.

1. Set the TF_WORKSPACE environment variable to the name of the workspace you wish to select. The following command sets the workspace to one.

   $ export TF_WORKSPACE="one"

   Note: If you use the workspace prefix configuration in your remote backend settings, set TF_WORKSPACE to the workspace name without the prefix.

   For example, given the following backend configuration, the full workspace name is prefix-one.

   terraform {
     backend "remote" {
       hostname     = "app.terraform.io"
       organization = "test-organization"
   
       workspaces {
         prefix = "prefix-"
       }
     }
   }

2. Verify the correct workspace is selected. When you run terraform workspace list with TF_WORKSPACE set to one, the output shows one as the active workspace.

   $ terraform workspace list
     012
     012-new
   * one
     two

Solution 2: Manually Create the .terraform/environment File

Terraform stores the currently selected workspace name in a file at .terraform/environment. You can create this file manually before running terraform init to pre-select the workspace.

1. If a .terraform directory already exists, remove it.

   $ rm -rf .terraform

2. Create a new, empty .terraform directory.

   $ mkdir .terraform

3. Create the .terraform/environment file and write the desired workspace name into it. The following command selects the foo workspace.

   $ printf '%s' foo > .terraform/environment

4. Run terraform init. Terraform will now use the workspace specified in the environment file and will not prompt for a selection.

   $ terraform init
   
   Initializing the backend...
   
   Successfully configured the backend "remote"! Terraform will automatically
   use this backend unless the backend configuration changes.
   
   Initializing provider plugins...
   - Checking for available provider plugins...
   - Downloading plugin for provider "null" (terraform-providers/null) 2.1.2...
   
   The following providers do not have any version constraints in configuration,
   so the latest version was installed.
   
   To prevent automatic upgrades to new major versions that may contain breaking
   changes, it is recommended to add version = "..." constraints to the
   corresponding provider blocks in configuration, with the constraint strings
   suggested below.
   
   * provider.null: version = "~> 2.1"
   
   Terraform has been successfully initialized!

5. Verify the correct workspace is selected by running terraform workspace list.

   $ terraform workspace list
     aaa
     bar
   * foo
     zzz