Terraform CLI can integrate with HCP Terraform, acting as a client for HCP Terraform's CLI-driven run workflow.
Hands On: Try the Migrate State to HCP Terraform tutorial.
You must configure the following settings to use HCP Terraform for a particular working directory:
terraform login
command.cloud
block to the directory's Terraform configuration, to specify
which organization and workspace(s) to use..terraformignore
file to specify files that shouldn't be
uploaded with the Terraform configuration when running plans and applies.After adding or changing a cloud
block, you must run terraform init
.
cloud
BlockThe cloud
block is a nested block within the top-level terraform
settings
block. It specifies which HCP Terraform workspaces to use for the current
working directory.
terraform {
cloud {
organization = "my-org"
hostname = "app.terraform.io" # Optional; defaults to app.terraform.io
workspaces {
project = "networking-development"
tags = ["networking", "source:cli"]
}
}
}
The cloud
block also has some special restrictions:
cloud
block.cloud
block cannot be used with state backends.
A configuration can use one or the other, but not both.cloud
block cannot refer to named values (like input variables, locals, or
data source attributes).The cloud
block only affects Terraform CLI's behavior. When HCP Terraform uses a configuration
that contains a cloud block - for example, when a workspace is configured to use a VCS provider
directly - it ignores the block and behaves according to its own workspace settings.
The cloud
block supports the following configuration arguments:
organization
- (Required) The name of the organization containing the
workspace(s) the current configuration should use.
workspaces
- (Required) A nested block that specifies which remote HCP Terraform workspaces to
use for the current configuration. The workspaces
block must contain exactly one of the
following arguments, each denoting a strategy for how workspaces should be mapped:
tags
- (Optional) A set of HCP Terraform workspace tags. You will be able to use
this working directory with any workspaces that have all of the specified tags,
and can use the terraform workspace
commands
to switch between them or create new workspaces. New workspaces will automatically have
the specified tags. This option conflicts with name
.
name
- (Optional) The name of a single HCP Terraform workspace. You will
only be able to use the workspace specified in the configuration with this working
directory, and cannot manage workspaces from the CLI (e.g. terraform workspace select
or
terraform workspace new
). This option conflicts with tags
.
project
- (Optional) The name of an HCP Terraform project. Workspaces that need creating
will be created within this project. terraform workspace list
will be filtered by workspaces
in the supplied project.
hostname
- (Optional) The hostname of a Terraform Enterprise installation, if using Terraform
Enterprise. Defaults to HCP Terraform (app.terraform.io).
token
- (Optional) The token used to authenticate with HCP Terraform.
We recommend omitting the token from the configuration, and instead using
terraform login
or manually configuring
credentials
in the
CLI config file.
You can use environment variables to configure one or more cloud
block attributes. This is helpful when you want to configure Terraform as part of a Continuous Integration (CI) pipeline. Terraform only reads these variables if the corresponding attribute is omitted from your configuration file. If you choose to configure the cloud
block entirely through environment variables, you must still add an empty cloud
block in your configuration file.
Use the following environment variables to configure the cloud
block:
TF_CLOUD_ORGANIZATION
- The name of the organization. Terraform reads this variable when organization
omitted from the cloud
block`. If both are specified, the configuration takes precedence.
TF_CLOUD_HOSTNAME
- The hostname of a Terraform Enterprise installation. Terraform reads this when hostname
is omitted from the cloud
block. If both are specified, the configuration takes precedence.
TF_CLOUD_PROJECT
- The name of an HCP Terraform project. Terraform reads this when workspaces.project
is omitted from the cloud
block. If both are specified, the cloud block configuration takes precedence.
TF_WORKSPACE
- The name of a single HCP Terraform workspace. Terraform reads this when workspaces
is omitted from the cloud
block. HCP Terraform will not create a new workspace from this variable; the workspace must exist in the specified organization. You can set TF_WORKSPACE
if the cloud
block uses tags. However, the value of TF_WORKSPACE
must be included in the set of tags. This variable also selects the workspace in your local environment. Refer to TF_WORKSPACE for details.
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, the upload will exclude
the following by default:
.git/
directories.terraform/
directories (exclusive of .terraform/modules
)The rules in .terraformignore
file resemble the rules allowed in a
.gitignore file:
#
) or blank lines are ignored./
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.