Connect to HCP Terraform

This topic describes how to connect the Terraform CLI to HCP Terraform. Integrating the CLI with HCP Terraform enables the CLI to act as a client for CLI-drive workflows. Refer toCLI-driven Run Workflow for additional information.

Hands On: Complete theMigrate State to HCP Terraform tutorial to learn more about integrating the CLI with HCP Terraform.

Overview

Connecting the Terraform CLI to HCP Terraform links the working directory that contains your Terraform configurations to one or more HCP Terraform workspaces. This allows team members with access to the workspace to provision and manage infrastructure using HCP Terraform. Additionally, HCP Terraform manages state data so that you do not have to maintain remote state objects. Refer to the following topics for additional information:

• State overview in the Terraform configuration language reference.
• Terraform State in HCP Terraform in the HCP Terraform documentation.

Complete the following steps to connect to HCP Terraform:

1. Provide credentials to HCP Terraform.
2. Define connection settings in your Terraform configuration.
3. Initialize the working directory.
4. Migrate state data. This step is optional.

Requirements

You must have a user profile in HCP Terraform with permissions to create a workspace. Refer toWorkspace Permissions in the HCP Terraform documentation for additional information.

Provide credentials

You must provide credentials to access HCP Terraform. We recommend using theterraform login command to log into Terraform. You can also provide a user token in the Terraform configuration. Refer to thetoken attribute in the Terraform configuration reference for additional information.

Define connection settings

Add acloud block to your Terraform configuration and configure the connection settings to link the working directory to an HCP Terraform workspace. Thecloud block is a member of theterraform block. Refer to theterraform block reference for additional information.

Specify the following settings in thecloud block:

• organization: Specifies the name of an HCP Terraform organization to connect to.
• workspaces.tags: Specifies a list of single-value string tags. Terraform links the working directory to existing workspaces in the organization that have matching tags. If there are no existing workspaces with matching tags, the Terraform CLI prompts you to create a new workspace that inherits the tags you specify in this field when you initialize the configuration.
• workspaces.name: You can specify the name of an existing workspace to associate with the Terraform configuration instead of using tags. If you configure thename, you cannot use thetags configuration.
• workspaces.project: You can specify the name of an existing project. Terraform associates the configuration with workspaces in the project that match thename ortags.

Refer to thecloud block reference for details about configuring thecloud block.

In the following example, the configuration links the working directory to all workspaces tagged withnetworking andsource:cli in thenetworking-development project:

terraform {  cloud {    organization= "my-org"    hostname= "app.terraform.io" # Optional; defaults to app.terraform.io    workspaces {      project= "networking-development"      tags= ["networking", "source:cli"]    }  }}

Initialize the working directory

After adding or changing acloud block, run theterraform init command to complete the set up.

By default, Terraform uploads a copy of Terraform configurations stored in the working directory when you run theterraform plan orterraform apply command, but you can add a.terraformignore file to the directory and specify files that you do not want to upload to HCP Terraform. Refer toExclude files for additional information.

If the working directory does not have an existing Terraform state file, you can immediately start using Terraform with HCP Terraform. Refer toCLI-driven run workflow for additional information.

If the directory has an existing state file associated with abackend configuration, Terraform prompts you to migrate state from any existing workspaces. Refer toMigrate state data for next steps.

Migrate state data

Complete the data migration process when prompted according to one of the following scenarios:

State is stored in alocal or state backend: If the working directory already has state data in one or more workspaces, Terraform prompts you to migrate the state to new HCP Terraform workspaces.State is stored in aremote backend: If the working directory is already connected to HCP Terraform with the remote backend, Terraform can continue using the same HCP Terraform workspaces. Change thebackend "remote" configuration to acloud block in this scenario.

Migrate local state

Run theterraform init command and follow the CLI prompts to migrate state data stored in a local or state backend.

HCP Terraform requires all workspaces to have a name. As a result, Terraform may also prompt you to rename your workspaces during the migration.

Terraform CLI-only workspaces represent multiple environments associated with the same configuration, such asproduction,staging, anddevelopment, but HCP Terraform workspaces can represent completely independent configurations and must have unique names within the HCP Terraform organization.

As a result, Terraform prompts you to rename workspaces according to a pattern relative to their existing names. The pattern is intended to indicate that the workspaces share configuration. A common strategy is<COMPONENT>-<ENVIRONMENT>-<REGION>, for examplenetworking-prod-us-east andnetworking-staging-us-east. Refer toWorkspace Naming in the HCP Terraform documentation for additional information.

Migrate remote backend

In theterraform block orterraform.tf file, replacebackend "remote" withcloud. Terraform will continue to use the same ste of HCP Terraform workspaces.

The following example migrates the state data for a single workspace namedmy-app-prod to an HCP Terraform organization namedmy-org.

terraform {-  backend "remote" {+    cloud {       organization= "my-org"       workspaces {          name= "my-app-prod"       }     }   }}

If theterraform block orterraform.tf file uses theprefix argument to connect to multiple workspaces, you can specify a list of single-value string tags in thetags argument instead of using thename argument. Duringterraform plan orterraform apply operations, Terraform associates the configuration with workspaces that match the specified tags.

The following example replaces themy-app- prefix with theapp:mine tag:

terraform {-  backend "remote" {+  cloud {     organization= "my-org"    workspaces {-      prefix= "my-app-"+      tags= ["app:mine"]    }   } }

Note that because thecloud block does not support theprefix argument, after you migrate your workspaces to HCP Terraform, you must refer to them by their full name when you use the Terraform CLI. For example, instead of running theterraform workspace select prod command, you would runterraform workspace select my-app-prod instead.

Exclude files

When executing a remoteplan orapply in aCLI-driven run,a copy of your configuration directory is uploaded to HCP Terraform. You can definepaths to exclude from upload by adding a.terraformignore file at the root of yourconfiguration directory. If this file is not present, Terraform still excludes the following directories by default:

• .git/ directories
• .terraform/ directories (exclusive of.terraform/modules)

The rules for defining.terraformignore are based on.gitignore files:

• Terraform ignores comments starting with#
• Terraform ignores blank lines.
• End a pattern with a forward slash/ to specify a directory.
• Negate a pattern by starting it with an exclamation point!. When ignoring large directories, negation patterns can impact performance. Place negation rules as early as possible within.terraformignore or avoid using them if possible.

Terraform parses the.terraformignore at the root of the configuration directory.