Skip to content
Tutorials Center
My learning

Topics

Lesson 5 of 37 ยท The HCL Language

HCL Syntax and Project Files

Learn HCL syntax for Terraform: blocks, labels, arguments, comments, identifiers, how .tf files are loaded, a good file layout, JSON syntax and override files.

Terraform configuration is written in HCL, the HashiCorp Configuration Language. HCL is deliberately small. It has only two core constructs, arguments and blocks, plus expressions that compute values. Once you can read those two shapes, you can read any Terraform file in the world. This lesson covers the syntax and how Terraform finds and combines your files.

All hcl code here is read-only; the Python stand-ins imitate the parsing and file-merging ideas.

Arguments

An argument assigns a value to a name:

HCL
instance_type = "t3.micro"

The name is on the left, = in the middle, an expression on the right. The value can be a literal (a string, a number, true, false, null), a list, a map, a reference or a function call. Arguments live inside blocks (or at the top level of a few special files such as .tfvars).

Blocks

A block is a container for arguments and other blocks. It has a type, zero or more labels, and a body in braces:

HCL
resource "aws_instance" "web" {
  ami           = "ami-0abcdef1234567890"
  instance_type = "t3.micro"

  root_block_device {
    volume_size = 20
  }
}

Here resource is the block type. It requires two labels: the resource type (aws_instance) and your local name (web). The body contains two arguments and one nested block, root_block_device, which has no labels. Block types decide how many labels they take:

Block type Labels Example
terraform 0 terraform { ... }
provider 1 provider "aws" { ... }
resource 2 resource "aws_s3_bucket" "logs" { ... }
data 2 data "aws_ami" "ubuntu" { ... }
variable 1 variable "region" { ... }
output 1 output "ip" { ... }
locals 0 locals { ... }
module 1 module "network" { ... }

The pair (type, local name) forms the address of a resource: aws_instance.web. Addresses must be unique within a module.

Argument versus nested block is a frequent source of confusion. tags = { Name = "web" } is an argument whose value is a map (note the =). root_block_device { ... } is a nested block (no =). The provider's documentation tells you which one each setting is, and Terraform will complain if you mix them up.

Python A tiny HCL block parser (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Identifiers and names

Names of blocks, variables and arguments are identifiers: letters, digits, underscores and hyphens, not starting with a digit. By convention Terraform code uses snake_case (web_server, instance_type). A resource's local name is for you only, never sent to the cloud. Choose names that describe the role (web, primary), and use this or main when a module has just one of something. Avoid repeating the type in the name: aws_s3_bucket.logs reads better than aws_s3_bucket.s3_bucket_logs.

Comments

HCL
# A single-line comment (preferred style)
// Also a single-line comment
/*
   A multi-line
   comment
*/

Use # for ordinary comments. Comment the why (a quota, a workaround, a link to a ticket); the code already shows the what.

Strings, numbers and layout

Strings use double quotes and support escapes (\n, \"). Single quotes are not strings in HCL. Numbers may be integers or decimals; Terraform does not distinguish int from float. Multi-line text uses heredocs, covered in Expressions. HCL is not whitespace sensitive, but the community style is two spaces of indentation, = signs aligned inside a block, blank lines between blocks, and meta-arguments (count, for_each, depends_on, provider) at the top. Run terraform fmt to get all of that automatically.

Files and the module as a unit

Terraform treats a directory as one module. It loads every *.tf file in the directory (not subdirectories), merges them into a single configuration, and ignores file names and order. You could put everything in one file or each resource in its own; Terraform behaves the same. The convention that most teams follow:

File Contents
main.tf Primary resources and data sources
providers.tf or versions.tf terraform and provider blocks
variables.tf All variable blocks
outputs.tf All output blocks
locals.tf locals blocks
terraform.tfvars Variable values for this environment

For a larger configuration, group files by topic instead: network.tf, database.tf, iam.tf. Both are fine; consistency matters more than the choice.

Python Merging files into one module (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Terraform reports the same kind of error: Error: Duplicate resource "aws_s3_bucket" configuration, because the address must be unique across all files of the module.

Other file kinds

  • *.tfvars and *.auto.tfvars hold variable values (input variables).
  • .terraform.lock.hcl records provider versions. It uses HCL but you rarely edit it.
  • *.tf.json files are an alternative syntax (below).
  • override.tf, *_override.tf merge on top of other files, replacing matching arguments. Use them sparingly; they exist for local tweaks and make configuration hard to follow.
  • .terraformignore (when packaging for Terraform Cloud) lists files to skip.

JSON syntax

Every HCL structure has a JSON equivalent in files ending in .tf.json. This is for programs that generate configuration, not for humans:

JSON
{
  "resource": {
    "aws_s3_bucket": {
      "logs": { "bucket": "example-app-logs-2026" }
    }
  }
}

JSON cannot hold comments and expressions need a "${...}" wrapper, so write HCL by hand and use JSON only when generating files with a script.

The terraform block

The special terraform block configures Terraform itself:

HCL
terraform {
  required_version = ">= 1.6.0, < 2.0.0"

  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 6.0"
    }
  }

  backend "s3" {
    bucket = "example-tfstate"
    key    = "prod/terraform.tfstate"
    region = "eu-central-1"
  }
}

It may not contain references to variables or resources, because Terraform must read it before anything is evaluated. Providers and backends get their own lessons later.

Common syntax mistakes

  • Forgetting labels: resource "aws_instance" { } fails because a resource needs a type and a name.
  • Single quotes: name = 'web' is an error; use "web".
  • = on a nested block: root_block_device = { ... } is wrong when the provider defines a block (though a few attributes accept either; see the docs).
  • Commas between arguments: not needed on separate lines. Commas separate list and map items.
  • Using a variable in a terraform block: not allowed.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the address of resource "aws_instance" "web" { ... }?

    A resource address is type.name, so aws_instance.web. It must be unique within the module.
  2. 2. How many labels does a variable block take?

    variable takes one label, its name. resource and data take two. terraform and locals take none.
  3. 3. Terraform loads all .tf files in a directory. What does file order do?

    All .tf files in the directory are merged into one module. Only override files have merge precedence.
  4. 4. Which is the preferred way to write a one-line comment?

    is the conventional comment style; // also works. Multi-line comments use /* ... */.

Summary

  • HCL has arguments (name = value) and blocks (type "label" { ... }).
  • Resource addresses are type.name and must be unique per module.
  • A directory is one module: all *.tf files are merged, in any order.
  • Common file names (main.tf, variables.tf, outputs.tf) are conventions, not rules.
  • .tf.json is for generated code; override files are best avoided.
  • The terraform block configures versions, providers and the backend and cannot use references.

Next: Types and Values