HCL Syntax and Configuration Files

The number and meaning of labels depends on the block type. A resource block takes two labels, the provider-defined resource type (docker_container) and a local name (catalog_api) that is unique within the module for that type. A variable block takes one label, the variable name. A terraform or locals block takes none. Each combination of block type and labels identifies one object, so declaring the same resource type and name twice is an error. Labels are written as quoted strings, and the style guide recommends wrapping both the type and the name in double quotes.

Because the labels together form an address, Terraform and its tools talk about objects by address: docker_container.catalog_api, var.environment, module.network, data.docker_network.default. The address of an object is the contract between files, which is why splitting blocks across files never changes behavior.

A single-line argument is name = expression, and each argument sits on its own line. Terraform does not use commas between arguments. Separating arguments with a newline is mandatory inside blocks; the single-line block form (variable "x" { type = string }) accepts exactly one argument. Which arguments are required, optional or computed is defined by the schema of the block, which for resource and data blocks comes from the provider (Providers).

Identifiers name arguments, block types and Terraform constructs such as resources, input variables, locals and modules. Valid characters are letters, digits, underscores and hyphens, and the first character must not be a digit. Terraform follows the Unicode identifier rules (UAX #31), extended to also accept the ASCII hyphen, so non-ASCII letters are legal. In practice teams use lowercase words separated by underscores, because hyphens force bracket notation in some contexts and underscores are what the style guide recommends.

Source: Terraform Docs — Configuration Syntax and Terraform Docs — Style Guide.

Configuration files must be encoded as UTF-8. Non-ASCII characters are allowed in identifiers, comments and string values, but the language delimiters themselves are ASCII. Both LF and CRLF line endings are accepted; LF is the idiom and formatting tools may convert CRLF to LF, which matters for diffs on mixed Windows and Unix teams.

.tfvars files are written in HCL syntax but contain nothing except assignments of values to variable names. The JSON form, .tfvars.json, is a single JSON object whose root keys are variable names. Terraform loads a definition file automatically when its name is terraform.tfvars, terraform.tfvars.json, or ends in .auto.tfvars or .auto.tfvars.json. All other files are passed explicitly with -var-file.

Source: Terraform Docs — Input Variables.

When several sources assign the same variable, the later in the following list wins; the first entry has the highest precedence.

The precedence rule is the reason secrets belong in TF_VAR_ environment variables or a secret store and not in a committed .tfvars file; see Variables, Outputs and Locals for validation, sensitivity and ephemeral variables.

An override file is a .tf or .tf.json file named exactly override.tf or override.tf.json, or ending in _override.tf or _override.tf.json. Terraform skips override files while loading the normal configuration and then processes them in lexicographical order by file name; within a file, blocks are processed by position, and later overrides win. Overrides exist for the rare case where the original files cannot or should not be edited — a generated file, or a local developer tweak that is not committed — and the style guide asks teams to use override.tf sparingly and to document its use in the original definitions.

An override block matches an original block with the same header (block type plus all labels). The merge rules are:

Source: Terraform Docs — Override Files.

.terraform.lock.hcl records which provider versions terraform init selected and their checksums (h1: and zh: hashes), so later runs make the same choices. It uses HCL syntax but is not a configuration file; it tracks providers only, not modules, and lives in the root working directory next to the .terraform cache directory. The file is generated, so you never write it by hand, but you do commit it so that dependency changes go through code review. terraform init -upgrade ignores the existing selections and picks the newest versions matching the constraints, and terraform providers lock -platform=... pre-records checksums for several operating systems and architectures, which matters when a team mixes macOS laptops and Linux CI runners. The full treatment is in Providers.

Source: Terraform Docs — Dependency Lock File.

Test files use the .tftest.hcl or .tftest.json extension, which is how Terraform discovers them. They are read only by terraform test, and their root-level blocks are test (optional, at most one, for settings such as parallel), run (one or more; each executes apply, the default, or plan, and may contain variables, module, providers, assert and expect_failures), variables (optional, at most one) and provider (zero or more). The test framework needs Terraform 1.6 or later, and provider mocking arrived in 1.7. Test files do not participate in the module’s configuration and cannot be referenced from it; see Testing.

Source: Terraform Docs — Tests.

.tfquery.hcl files are inputs to the terraform query command: they hold parameters that search for resources in existing infrastructure so that you can import them into state and manage them as code. A query file may contain list, provider, variable and locals blocks, and Terraform loads every query file in the root configuration directory. The list block takes a resource type and a label, the required provider meta-argument, optional count or for_each (mutually exclusive), include_resource (return full objects instead of only identities), limit (default 100) and a provider-specific config block. List resources and terraform query arrived in Terraform 1.14; the workflow is explained in Import and Query.

Source: Terraform Docs — Query Files and Terraform Docs — list block reference.

Terraform Stacks (HCP Terraform) split infrastructure definition from deployment into two file types, both placed at the root of the Stack’s repository:

The suffix determines the file type and the file name before it is free, so a Stack is usually split into files such as components.tfcomponent.hcl, providers.tfcomponent.hcl and deployments.tfdeploy.hcl. HCP Terraform processes every matching file in the root directory. Stacks are not ordinary modules and the CLI’s init, plan and apply do not read these files; they are the subject of Terraform Stacks. A third suffix, .tfstacks.hcl, is not described on the official Stack file reference, so this page does not rely on it.

Source: Terraform Docs — Stack Configuration Files.

OpenTofu stores code in plain text files with the .tf or .tofu extension, and its JSON variant uses .tf.json or .tofu.json. The practical consequence is a precedence rule: when foo.tf and foo.tofu exist in the same directory, OpenTofu loads only the .tofu file and ignores the .tf file, while Terraform does the opposite — it knows nothing about .tofu and reads only the .tf file. A module author can therefore ship foo.tf for Terraform users and foo.tofu for OpenTofu users with OpenTofu-only features (state encryption, early variable evaluation, provider for_each and so on), without the two tools tripping over each other. More on the fork and the other differences is in OpenTofu.

Source: OpenTofu Docs — Files.

The figure shows which files contribute to a run. Normal configuration files are merged first, override files are applied on top, variable values are collected from the sources in the precedence order above, and the lock file constrains which provider builds are installed. Test, query and Stacks files are not part of this pipeline at all: each is read by its own command.

Inside cloud, organization and workspaces are required for HCP Terraform. The workspaces block selects either a single workspace with name or all workspaces carrying a set of tags (a list or map), and the two are mutually exclusive; project selects the HCP Terraform project. hostname defaults to app.terraform.io and is how a Terraform Enterprise instance is addressed. The token argument exists but the documentation advises against writing credentials in configuration: use terraform login or the CLI configuration file instead. Key-only tags need Terraform Enterprise v202411-1 or later, or Terraform 1.10 or later.

Environment variables can supply the same values: TF_CLOUD_ORGANIZATION, TF_CLOUD_HOSTNAME, TF_CLOUD_PROJECT and TF_WORKSPACE. They apply only when the matching attribute is absent from the configuration (the configuration wins if both are set), and to configure cloud entirely through environment variables an empty cloud block must still be present. TF_WORKSPACE cannot create a workspace; it must already exist, and when tags is used it must be one of the tagged workspaces.

Source: Terraform Docs — terraform block reference. See HCP Terraform and Enterprise for workspaces, runs and projects.

The experiments setting is intended for features still being designed in Terraform’s own release cycle. Because of the warning on every run, it is something to enable on a branch for evaluation, never in the baseline of a module that others consume. OpenTofu keeps the terraform block and adds an encryption block inside it for state and plan encryption; see OpenTofu.

Source: Terraform Docs — Style Guide.

As a module grows, split main.tf by concern — network.tf, storage.tf, compute.tf — so that a maintainer can find any resource immediately.

Do not commit state files and their backups, the state lock info file, the .terraform directory, saved plan files or .tfvars files containing sensitive data. Do commit all code, .terraform.lock.hcl, a .gitignore and a README.md describing inputs and outputs. Pin provider versions in required_providers, set required_version to a minimum Terraform version, and pin registry modules with the version argument to a specific major and minor version (Terraform ignores version for local modules). Registry module repositories are named terraform-<PROVIDER>-<NAME>.

Source: Terraform Docs — Style Guide.