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.
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:
Complete the following steps to connect to HCP Terraform:
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.
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.
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"
}
}
}
}
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.
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.
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.
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.
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:
#
/
to specify a directory.!
. 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.
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4