terraform block reference

This topic provides reference information about theterraform block. Theterraform block allows you to configure Terraform behavior, including the Terraform version, backend, integration with HCP Terraform, and required providers.

Configuration model

The following list outlines attribute hierarchy, data types, and requirements in theterraform block. Click on an attribute for details.

• terraform
  • required_version   string
  • required_providers   block
    • <PROVIDER>   block
      • version   string
      • source   string
  • provider_meta "<LABEL>"   block
  • backend "<BACKEND_TYPE>"   block | mutually exclusive withcloud
  • cloud   block | mutually exclusive withbackend
    • organization   string | required when connecting to HCP Terraform
    • workspaces   block | required when connecting to HCP Terraform
      • tags   list | mutually exclusive withname
      • name   string | mutually exclusive withtags
      • project   string
    • hostname   string |app.terraform.io
    • token   string
  • experiments   list

Complete configuration

The followingterraform block defines all of the supported built-in arguments you can set:

terraform {  required_version= "<version>"  required_providers {    <PROVIDER> {      version= "<version-constraint>"      source= "<provider-address>"    }  }  provider_meta "<LABEL>" {    # Shown for completeness but only used for specific cases  }  backend "<TYPE>" {    # `backend` is mutually exclusive with `cloud`    "<ARGUMENTS>"  }  cloud {    # `cloud` is mutually exclusive with `backend`    organization= "<organization-name>"    workspaces {      tags= ["<tag>" ]      name= "<workspace-name>"      project= "<project-name>"    }    hostname= "app.terraform.io"    token- "<TOKEN>"  }  experiments= ["<feature-name>" ]}

Specification

Theterraform block supports the following configuration

terraform block

Parent block that contains configurations that define Terraform behavior. You can only use constant values in theterraform block. Arguments in theterraform block cannot refer to named objects, such as resources and input variables. Additionally, you cannot use built-in Terraform language functions in the block.

required_version

Specifies which version of the Terraform CLI is allowed to run the configuration.

terraform {  required_version= "<Terraform version>"  # . . .}

Refer toVersion constraints for details about the supported syntax for specifying version constraints.

Use Terraform version constraints in a collaborative environment to ensure that everyone is using a specific Terraform version, or using at least a minimum Terraform version that has behavior expected by the configuration.

Terraform prints an error and exits without taking actions when you use a version of Terraform that does not meet the version constraints to run the configuration.

Modules associated with a configuration may also specify version constraints. You must use a Terraform version that satisfies all version constraints associated with the configuration, including constraints defined in modules, to perform operations. Refer toModules for additional information about Terraform modules.

Therequired_version configuration applies only to the version of Terraform CLI and not versions of provider plugins. Refer toProvider Requirements for additional information.

Summary

• Data type: String.
• Default: None.
• Example:Add a provider

required_providers

Specifies all provider plugins required to create and manage resources specified in the configuration.

terraform {  required_providers {    <PROVIDER> {}  }  # . . .}

Each local provider name maps to a source address and a version constraint. Refer to each Terraform provider’s documentation in thepublic Terraform Registry, or your private registry, for instructions on how to configure attributes in therequired_providers block.

Summary

• Data type: Block.
• Default: None.
• Example:Add a provider

Provider-specific settings

Specifies the name of the provider you want to require. Refer toProvide Configuration for instructions on how to configure providers.

terraform {  required_providers {    <PROVIDER> {      version= "<version-constraint>"      source= "<address>"    }  }  # . . .}

You can specify the following arguments:

Summary

• Data type: Block.
• Default: None.
• Example:Add a provider

provider_meta "<LABEL>"

Specifies metadata fields that a provider may expect.

terraform {  provider_meta {    <DATA>  }  # . . .}

Individual modules can populate the metadata fields independently of any provider configuration. Refer toProvider Metadata for additional information.

Summary

• Data type: Block.
• Default: None.

backend "<BACKEND_TYPE>"

Specifies a mechanism for storing Terraform state files.

terraform {  backend "<TYPE>" {    <backend-configuration>  }  # . . .}

Thebackend block takes a backend type as an argument. Refer toBackend Configuration for details about configuring thebackend block.

You cannot configure abackend block when the configuration also contains acloud configuration for storing state data.

Summary

• Data type: Block.
• Default:local

cloud

Specifies a set of attributes that allow the Terraform configuration to connect to either HCP Terraform or a Terraform Enterprise installation.

terraform {  cloud  {    <cloud-configuration>  }  # . . .}

HCP Terraform and Terraform Enterprise provide state storage, remote execution, and other benefits. Refer to theHCP Terraform andTerraform Enterprise documentation for additional information.

You can only provide onecloud block per configuration.

You cannot configure acloud block when the configuration also contains abackend configuration for storing state data.

Thecloud block cannot refer to named values, such as input variables, locals, or data source attributes.

Summary

• Data type: Block.
• Default: None.
• Example:Connect to HCP Terraform

organization

Specifies the name of the organization you want to connect to.

terraform {  cloud  {    organization= "<organization-name>"  }  # . . .}

Instead of hardcoding the organization as a string, you can alternatively use theTF_CLOUD_ORGANIZATION environment variable.

Summary

• Data type: String
• Required when connecting to HCP Terraform
• Example:Connect to HCP Terraform

workspaces

Specifies metadata for matching workspaces in HCP Terraform.

terraform {  cloud  {    workspaces {      tags= ["<workspace-tag>" ]# Mutually exclusive with `name`      name= "<workspace-name>" # Mutually exclusive with `tags`      project= "<project-name>"    }  }  # . . .}

Terraform associates the configuration with workspaces managed in HCP Terraform that match the specified tags, name, or project. You can specify the following metadata in theworkspaces block:

Summary

• Data type: Block.
• Required when connecting to HCP Terraform
• Example:Connect to HCP Terraform

hostname

Specifies the hostname for a Terraform Enterprise deployment.

terraform {  cloud  {    hostname= "app.terraform.io"  }  # . . .}

Instead of hardcoding the hostname of the Terraform Enterprise deployment, you can alternatively use theTF_CLOUD_HOSTNAME environment variable.

Summary

• Data type: String.
• Required when connecting to Terraform Enterprise.
• Default:app.terraform.io
• Example:Connect to Terraform Enterprise

token

Specifies a token for authenticating with HCP Terraform.

terraform {  cloud  {    token= "<token>"  }  # . . .}

We recommend omitting the token from the configuration and either using theterraform login command or manually configuring credentials in theCLI configuration file instead.

Summary

• Data type: String.
• Default: None.
• Example:Connect to Terraform Enterprise

experiments

Specifies a list of experimental feature names that you want to opt into.

terraform {  experiments= ["<feature-name>" ]  # . . .}

In releases where experimental features are available, you can enable them on a per-module basis.

Experiments are subject to arbitrary changes in later releases and, depending on the outcome of the experiment, may change significantly before final release or may not be released in stable form at all. Breaking changes may appear in minor and patch releases. We do not recommend using experimental features in Terraform modules intended for production.

Modules with experiments enabled generate a warning on everyterraform plan orterraform apply operation. If you want to try experimental features in a shared module, we recommend enabling the experiment only in alpha or beta releases of the module.

Refer to theTerraform changelog for information about experiments and to monitor the release notes about experiment keywords that may be available.

Summary

• Data type: List.
• Default: None.

Environment variables for thecloud block

You can use environment variables to configure one or morecloud block attributes. This is helpful when you want to use the same Terraform configuration in different HCP Terraform organizations and projects. Terraform only uses these variables if you do not define corresponding attributes in your configuration. If you choose to configure thecloud block entirely through environment variables, you must still add an emptycloud block in your configuration file.

Use the following environment variables to configure thecloud block:

• TF_CLOUD_ORGANIZATION - The name of the organization. Terraform reads this variable whenorganization is 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 an HCP Terraform 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 HCP Terraform workspace. Terraform reads this whenworkspaces is omitted from thecloud block. HCP Terraform 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 toTF_WORKSPACE for details.

Examples

The following examples show how to write configuration for common use cases.

Add a provider

The following configuration requires theaws provider version 2.7.0 or later from the public Terraform registry:

terraform {  required_providers {    aws= {      version= ">= 2.7.0"      source= "hashicorp/aws"    }  }}

Connect to HCP Terraform

In the following example, the configuration links the working directory to workspaces in theexample_corp organization that contain thelayer=app tag:

terraform {  cloud {    organization= "example_corp"    workspaces {      tags= {        layer= "app"      }    }  }}

Connect to Terraform Enterprise

In the following example, the configuration links the working directory to workspaces in theexample_corp organization that contain theapp key-only tag. Key-only tags must be used with versions of Terraform Enterprise prior to v202411-1 or versions of Terraform prior to v1.10. Thehostname field is required in the configuration unless you use theTF_CLOUD_HOSTNAME environment variable:

terraform {  cloud {    organization= "example_corp"    hostname= "my.terraform-enterprise.host"    workspaces {      tags= ["app"]    }  }}

Connect to Terraform Enterprise using environment variables

In the following example, Terraform checks theTF_CLOUD_ORGANIZATION andTF_CLOUD_HOSTNAME environment variables and automatically populates theorganization andhostname arguments. During initialization, the local Terraform CLI connects the working directory to Terraform Enterprise using those values. As a result, Terraform links the configuration to either HCP Terraform or Terraform Enterprise and allows teams to reuse the configuration in different continuous integration pipelines:

terraform {  cloud {    workspaces {      tags= ["app"]    }  }}