How-to use the remote backend and Terraform CLI to run plan and state operations locally

Introduction

This article outlines how to add a remote backend configuration to an existing HCP Terraform or Terraform Enterprise workspace configuration. This allows you to use the Terraform CLI on your local machine to run plans and interact with the workspace's state.

Expected Outcome

After following this guide, you will be able to use Terraform CLI commands like terraform plan and terraform state locally to interact with a remote workspace in HCP Terraform or Terraform Enterprise.

Prerequisites

• An existing workspace in HCP Terraform or Terraform Enterprise.
• A local copy of the Terraform configuration for the workspace.
• For Terraform versions 1.1.0 and later, HashiCorp recommends using the cloudsettings block instead of the remote backend. Follow the CLI-driven runs configuration guide for that method. This guide specifically covers the remote backend.

Procedure

1. Navigate to the HCP Terraform or Terraform Enterprise workspace you want to manage locally.
2. Obtain a local copy of the Terraform configuration used to perform runs in this workspace.
3. Within the local configuration directory, create a new file, such as backend.tf.

4. In the new file, add a terraform block containing a remote backend configuration.

   terraform {
     backend "remote" {
       hostname     = "TFE_HOSTNAME"
       organization = "ORG_NAME"
   
       workspaces {
         name = "WORKSPACE_NAME"
       }
     }
   }

5. Update the placeholder values:
   • TFE_HOSTNAME: For Terraform Enterprise, use the base URL for your instance. For HCP Terraform, you can delete this line, as it defaults to app.terraform.io.
   • ORG_NAME: Use the name of your HCP Terraform or Terraform Enterprise organization.
   • WORKSPACE_NAME: Use the name of the workspace.

6. Ensure the version of Terraform you use at the command line matches the version specified in the workspace settings (Settings > General).

   

   You can also find the version in the terraform_version entry of the most recent state file.

   

   Verify your local version matches.

   $ terraform version
   Terraform v1.0.0
   on darwin_amd64

7. Log in to your HCP Terraform or Terraform Enterprise instance from the CLI. For Terraform v0.12.21 or later, run terraform login. If connecting to Terraform Enterprise, specify its hostname.

   $ terraform login <hostname>

8. When prompted, enter yes and paste your API token once. Note there is no indication once pasted. Press return/enter to complete saving local credentials.

   

   Note: If you receive a Token is invalid error, ensure you copied the entire token correctly. Some browsers may not be compatible with the built-in copy button in the UI.

9. In your Terraform configuration directory, initialize the backend.

   $ terraform init

   The output confirms successful initialization with the remote backend.

   

10. You can now use the terraform state command to interact with the remote state. For a list of available subcommands, refer to the Command: state documentation.

11. You can also make modifications to your local configuration and run terraform plan to queue a run in the remote workspace.

    Note: Workspaces connected to a Version Control System (VCS) do not allow terraform apply operations initiated from the CLI using the remote backend.

Additional Information

• Configuring Workspace VCS connections
• Provider requirements
• Troubleshooting Terraform