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 to CLI-driven Run Workflow for additional information.

Hands On: Complete the Migrate 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 to Workspace Permissions in the HCP Terraform documentation for additional information.

Provide credentials

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

Define connection settings

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

Specify the following settings in the cloud block:

• organization: Specifies the name of an HCP Terraform organization to connect to.
• workspaces.tags: Specifies either a map of tag strings or a list of key-only string tags (legacy style). 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 applies 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 the name, you cannot use the tags configuration.
• workspaces.project: You can specify the name of an existing project. Terraform associates the configuration with workspaces in the project that match the name or tags.

Refer to the cloud block reference for details about configuring the cloud block.

In the following example, the configuration links the working directory to all workspaces tagged with networking and source:cli in the networking-development project:

terraform {
  cloud {
    organization = "my-org"
    hostname = "app.terraform.io" # Optional; defaults to app.terraform.io

    workspaces {
      project = "networking-development"

      tags = {
        layer = "networking"
        source = "cli"
      }
    }
  }
}

Initialize the working directory

After adding or changing a cloud block, run the terraform init command to complete the set up.

By default, Terraform uploads a copy of Terraform configurations stored in the working directory when you run the terraform plan or terraform 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 to Exclude 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 to CLI-driven run workflow for additional information.

If the directory has an existing state file associated with a backend configuration, Terraform prompts you to migrate state from any existing workspaces. Refer to Migrate 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 a local 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 a remote 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 the backend "remote" configuration to a cloud block in this scenario.

Migrate local state

Run the terraform 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 as production, staging, and development, 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 example networking-prod-us-east and networking-staging-us-east. Refer to Workspace Naming in the HCP Terraform documentation for additional information.

Migrate remote backend

In the terraform block or terraform.tf file, replace backend "remote" with cloud. Terraform will continue to use the same ste of HCP Terraform workspaces.

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

terraform {
-  backend "remote" {
+    cloud {
       organization = "my-org"

       workspaces {
          name = "my-app-prod"
       }
     }
   }
}

If the terraform block or terraform.tf file uses the prefix argument to connect to multiple workspaces, you can specify a list of key-value string tags in the tags argument instead of using the name argument. During terraform plan or terraform apply operations, Terraform associates the configuration with workspaces that match the specified tags.

The following example replaces the my-app- prefix with the app=mine tag:

terraform {
-  backend "remote" {
+  cloud {
     organization = "my-org"

    workspaces {
-      prefix = "my-app-"
+      tags = {
+        app = "mine"
+      }
    }
   }
 }

Note that because the cloud block does not support the prefix 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 the terraform workspace select prod command, you would run terraform workspace select my-app-prod instead.

Exclude files

When executing a remote plan or apply in a CLI-driven run, a copy of your configuration directory is uploaded to HCP Terraform. You can define paths to exclude from upload by adding a .terraformignore file at the root of your configuration 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.