HCL Syntax Basics

HashiCorp Configuration Language — HCL — is the language every Terraform configuration is written in. It is built around blocks, arguments, and expressions, and it is designed to be read and reviewed rather than fully programmed. You describe resources and the relationships between them, and Terraform figures out the order. Learning to read a block's anatomy makes every provider's documentation immediately usable.

HCL is not a general-purpose programming language, and trying to use it as one is the first thing that trips people up. There are no if statements or for loops as control flow; the language is expression-based. Once you accept that, its small surface becomes an advantage — configurations stay declarative and reviewable.

Blocks and Arguments

Everything in HCL is a block or an argument. A block has a type, optional labels, and a body in braces: resource "aws_instance" "web" { ... } is a block of type resource with two labels — the resource type and your chosen name. Inside, arguments are simple key = value pairs. The snippet below shows the anatomy: the block type, its two labels, and its arguments.

# block type ── resource type ─── local name
resource "aws_instance" "web" {
  ami           = "ami-0abc123"   # arguments are key = value
  instance_type = "t3.micro"
  tags = {
    Name = "web-server"
  }
}

Types and Values

HCL values are strings, numbers, bools, and the collection types: lists (ordered), maps (key-value), and objects (structured). Strings use double quotes, and multi-line strings use heredocs (<<-EOT ... EOT) for things like user-data scripts and policy documents. These types are the same ones variables and outputs use, so learning them here pays off across the whole language.

References and Interpolation

The connective tissue of a configuration is references. Writing aws_vpc.main.id inside a subnet pulls that VPC's id attribute — and, crucially, tells Terraform the subnet depends on the VPC, so it builds them in the right order. Inside a string, ${...} interpolation embeds an expression: "web-${var.environment}". In modern Terraform a bare reference needs no ${} wrapper; reserve interpolation for when you are building a string around a value.

Comments, Formatting, and terraform fmt

Comments use # or // for a line and /* */ for a block. Formatting is not a matter of taste: terraform fmt rewrites files into one canonical style, which ends every alignment and indentation debate before it starts. Run it on save and enforce it in CI, and code review never spends a second on whitespace.

How Files Are Organized

Terraform loads every .tf file in a directory and merges them — the parser does not care about filenames or how you split things up. The common convention of main.tf, variables.tf, and outputs.tf is purely for humans: it makes a configuration predictable to navigate. You could put everything in one file or spread it across twenty; Terraform sees the same merged result either way.