Terraform Cloud Settings
Terraform CLI can integrate with Terraform Cloud, acting as a client for Terraform Cloud's CLI-driven run workflow.
Hands On: Try the Migrate State to Terraform Cloud tutorial.
You must configure the following settings to use Terraform Cloud for a particular working directory:
- Provide credentials to access Terraform Cloud, preferably by using the
terraform login
command. - Add a
cloud
block to the directory's Terraform configuration, to specify which organization and workspace(s) to use. - Optionally, use a
.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
.
The cloud
Block
The cloud
block is a nested block within the top-level terraform
settings
block. It specifies which Terraform Cloud workspaces to use for the current
working directory.
The cloud
block also has some special restrictions:
- A configuration can only provide one
cloud
block. - A
cloud
block cannot be used with state backends. A configuration can use one or the other, but not both. - A
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 Terraform Cloud 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.
Arguments
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 Terraform Cloud workspaces to use for the current configuration. Theworkspaces
block must contain exactly one of the following arguments, each denoting a strategy for how workspaces should be mapped:tags
- (Optional) A set of Terraform Cloud workspace tags. You will be able to use this working directory with any workspaces that have all of the specified tags, and can use theterraform workspace
commands to switch between them or create new workspaces. New workspaces will automatically have the specified tags. This option conflicts withname
.name
- (Optional) The name of a single Terraform Cloud 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
orterraform workspace new
). This option conflicts withtags
.project
- (Optional) The name of a Terraform Cloud 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 Terraform Cloud (app.terraform.io).token
- (Optional) The token used to authenticate with Terraform Cloud. We recommend omitting the token from the configuration, and instead usingterraform login
or manually configuringcredentials
in the CLI config file.
Environment Variables
Note: CLI integration environment variables are supported in Terraform v1.2.0 and later.
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.
Warning: Remote execution with non-interactive workflows requires auto-approved deployments. Minimize risk of unpredictable infrastructure changes and configuration drift by making sure that no one can change your infrastructure outside of your automated build pipeline. Refer to Non-Interactive Workflows for details.
Use the following environment variables to configure the cloud
block:
TF_CLOUD_ORGANIZATION
- The name of the organization. Terraform reads this variable whenorganization
omitted from thecloud
block`. If both are specified, the configuration takes precedence.TF_CLOUD_HOSTNAME
- The hostname of a Terraform Enterprise installation. Terraform reads this whenhostname
is omitted from thecloud
block. If both are specified, the configuration takes precedence.TF_CLOUD_PROJECT
- The name of a Terraform Cloud project. Terraform reads this whenworkspaces.project
is omitted from thecloud
block. If both are specified, the cloud block configuration takes precedence.TF_WORKSPACE
- The name of a single Terraform Cloud workspace. Terraform reads this whenworkspaces
is omitted from thecloud
block. Terraform Cloud will not create a new workspace from this variable; the workspace must exist in the specified organization. You can setTF_WORKSPACE
if thecloud
block uses tags. However, the value ofTF_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.
Excluding Files from Upload with .terraformignore
When executing a remote plan
or apply
in a CLI-driven run,
a copy of your configuration directory is uploaded to Terraform Cloud. 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:
- Comments (starting with
#
) or blank lines are ignored. - End a pattern with a forward slash
/
to specify a directory. - Negate a pattern by starting it with an exclamation point
!
.
Note: Unlike .gitignore
, only the .terraformignore
at the root of the configuration directory is considered.