HCP Terraform Settings

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:

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 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:

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.

Arguments

The cloud block supports the following configuration arguments:

Environment Variables

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:

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 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:

The rules in .terraformignore file resemble the rules allowed in a .gitignore file: