HCL

# Single-line comment
// Alternative single-line comment
/* Multi-line
   comment */

# Argument assignment
image_id = "abc123"

Simple key-value pairs form the foundation of HCL configuration.

resource "aws_instance" "example" {
  ami = "ami-abc123"

  # Nested block
  network_interface {
    # ...
  }
}

Blocks have a type, optional labels, and contain arguments or nested blocks.

# String
name = "hello"

# Number
count = 42

# Bool
enabled = true

# List
zones = ["us-east-1a", "us-east-1b"]

# Map
tags = {
  Name = "web-server"
}

# Null
optional = null

HCL supports primitive types (string, number, bool) and complex types (list, map, set).

multiline = <<-EOT
  Hello
  World
EOT

Heredoc syntax for multiline strings. Use <<- to strip leading whitespace.

name = "World"
greeting = "Hello, ${var.name}!"

Embed expressions in strings using ${} syntax.

message = "Hello, %{ if var.name != "" }${var.name}%{ else }unnamed%{ endif }!"

Use %{ if } directive for conditional content in strings.

servers = <<EOT
%{ for ip in aws_instance.example[*].private_ip ~}
server ${ip}
%{ endfor ~}
EOT

Generate repeated content. The ~ strips whitespace/newlines.

literal_interpolation = "$${not_a_variable}"
literal_directive = "%%{not_a_directive}"

Use $$ and %% to escape interpolation and directives.

resource "aws_instance" "web" {
  ami           = "ami-a1b2c3d4"
  instance_type = "t2.micro"

  tags = {
    Name = "web-server"
  }
}

Declares infrastructure resource to create.

variable "instance_type" {
  description = "EC2 instance type"
  type        = string
  default     = "t2.micro"
  sensitive   = false

  validation {
    condition     = contains(["t2.micro", "t2.small"], var.instance_type)
    error_message = "Invalid type."
  }
}

Input variables with validation. Reference with var.instance_type.

output "instance_ip" {
  description = "Public IP of instance"
  value       = aws_instance.web.public_ip
  sensitive   = false
}

Output values for modules or CLI display.

locals {
  common_tags = {
    Project = "MyApp"
    Env     = var.environment
  }

  name = "${var.environment}-web"
}

Computed values reused throughout config. Reference with local.common_tags.

data "aws_ami" "ubuntu" {
  most_recent = true
  owners      = ["099720109477"]

  filter {
    name   = "name"
    values = ["ubuntu/images/*22.04*"]
  }
}

Query existing infrastructure. Reference with data.aws_ami.ubuntu.id.

module "vpc" {
  source  = "terraform-aws-modules/vpc/aws"
  version = "3.14.0"

  name = "my-vpc"
  cidr = "10.0.0.0/16"
}

Reusable configuration packages. Reference outputs with module.vpc.vpc_id.

provider "aws" {
  region = "us-east-1"

  default_tags {
    tags = {
      ManagedBy = "Terraform"
    }
  }
}

Configure provider plugin.

provider "aws" {
  alias  = "west"
  region = "us-west-2"
}

resource "aws_instance" "west" {
  provider = aws.west
  ami      = "ami-456"
}

Multiple configurations for same provider.

terraform {
  required_version = ">= 1.3"

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

  backend "s3" {
    bucket = "my-terraform-state"
    key    = "prod/terraform.tfstate"
    region = "us-east-1"
  }
}

Configure Terraform behavior, providers, and state backend.

instance_type = var.environment == "prod" ? "t3.large" : "t2.micro"

Classic ternary operator: condition ? true_value : false_value.

# Transform
upper_names = [for name in var.names : upper(name)]

# Filter
prod = [for inst in var.instances : inst if inst.env == "prod"]

# With index
indexed = [for i, v in var.list : "${i}: ${v}"]

List comprehensions with optional filtering and indexing.

# Transform map
upper_tags = {for k, v in var.tags : k => upper(v)}

# Filter map
filtered = {for k, v in var.tags : k => v if v != ""}

# Group by (with ...)
by_role = {for name, user in var.users : user.role => name...}

Map comprehensions. Use ... for grouping mode.

# Get all IDs
instance_ids = aws_instance.example[*].id

# Nested access
private_ips = aws_instance.example[*].network_interface[0].private_ip

Shorthand for extracting attributes. Equivalent to [for inst in ... : inst.id].

# Single resource
aws_instance.web.id

# With count
aws_instance.server[0].id
aws_instance.server[*].id

# With for_each
aws_instance.server["web"].id

Reference resource attributes in expressions.

resource "aws_instance" "server" {
  count = 4

  ami = "ami-a1b2c3d4"

  tags = {
    Name = "Server ${count.index}"
  }
}

Create multiple instances. Access index with count.index. Reference: aws_instance.server[0].

# With set
resource "aws_instance" "server" {
  for_each = toset(["web", "api", "worker"])

  ami = "ami-a1b2c3d4"
  tags = {
    Name = each.key
  }
}

Create instances from set/map. Access with each.key and each.value. Reference: aws_instance.server["web"].

resource "aws_iam_user" "users" {
  for_each = {
    alice = "admin"
    bob   = "developer"
  }

  name = each.key
  tags = {
    Role = each.value
  }
}

Use maps for key-value iteration.

resource "aws_iam_role_policy" "example" {
  role   = aws_iam_role.example.id
  policy = "..."

  depends_on = [aws_iam_role.example]
}

Explicit dependency when implicit dependencies aren't sufficient.

resource "aws_instance" "west" {
  provider = aws.west
  ami      = "ami-456"
}

Use specific provider configuration.

lifecycle {
  create_before_destroy = true
}

Create replacement before destroying original. Useful for zero-downtime changes.

lifecycle {
  prevent_destroy = true
}

Terraform will error if resource deletion attempted. Doesn't prevent manual deletion.

lifecycle {
  ignore_changes = [
    tags,
    ami,
  ]
}

Ignore changes to specific attributes.

lifecycle {
  ignore_changes = all
}

Ignore all attribute changes. Prevents any updates to resource.

lifecycle {
  replace_triggered_by = [
    aws_ecs_service.svc.id
  ]
}

Force replacement when referenced resource changes.

lifecycle {
  precondition {
    condition     = data.aws_ami.example.architecture == "x86_64"
    error_message = "AMI must be x86_64."
  }
}

Validate conditions before apply.

lifecycle {
  postcondition {
    condition     = self.public_dns != ""
    error_message = "Instance must have public DNS."
  }
}

Validate conditions after apply. Use self to reference resource.

resource "aws_security_group" "example" {
  name = "example"

  dynamic "ingress" {
    for_each = var.ingress_rules
    content {
      from_port   = ingress.value.from_port
      to_port     = ingress.value.to_port
      protocol    = ingress.value.protocol
      cidr_blocks = ingress.value.cidr_blocks
    }
  }
}

Generate repeated nested blocks. The block label becomes the default iterator name.

dynamic "ingress" {
  for_each = var.ingress_rules
  iterator = rule
  content {
    from_port = rule.value.from_port
    to_port   = rule.value.to_port
  }
}

Use iterator to customize the iterator name instead of block label.

format("instance-%03d", 42)
# "instance-042"

Printf-style string formatting.

join(", ", ["web", "api", "db"])
# "web, api, db"

split("-", "web-server-01")
# ["web", "server", "01"]

Join list to string or split string to list.

replace("hello world", "world", "tf")
# "hello tf"

Replace substring in string.

trimspace("  hello  ")
# "hello"

Remove leading/trailing whitespace.

upper("hello")  # "HELLO"
lower("HELLO")  # "hello"

Change string case.

substr("hello world", 0, 5)
# "hello"

Extract substring: substr(string, offset, length).

regexall("[0-9]+", "abc123def456")
# ["123", "456"]

Extract all regex matches.

concat(["a", "b"], ["c", "d"])
# ["a", "b", "c", "d"]

Combine multiple lists.

flatten([["a", "b"], ["c", "d"]])
# ["a", "b", "c", "d"]

Flatten nested lists.

merge({a = 1}, {b = 2})
# {a = 1, b = 2}

Combine multiple maps.

lookup({a = 1}, "b", 0)
# 0

Get map value with default: lookup(map, key, default).

element(["a", "b", "c"], 4)
# "b"

Get list element by index (wraps around).

length(["a", "b", "c"])  # 3

Get collection length.

keys({a = 1, b = 2})    # ["a", "b"]
values({a = 1, b = 2})  # [1, 2]

Extract map keys or values.

contains(["a", "b"], "a")
# true

Check if list contains value.

distinct(["a", "b", "a"])
# ["a", "b"]

Remove duplicates from list.

slice(["a", "b", "c", "d"], 1, 3)
# ["b", "c"]

Extract sublist: slice(list, start, end).

sort(["c", "a", "b"])
# ["a", "b", "c"]

Sort list alphabetically.

range(5)
# [0, 1, 2, 3, 4]

Generate sequence of numbers.

max(5, 12, 9)  # 12
min(5, 12, 9)  # 5

Find maximum or minimum value.

abs(-5)  # 5

Absolute value.

ceil(5.2)   # 6
floor(5.8)  # 5

Round up or down.

pow(2, 3)  # 8

Exponentiation: pow(base, exponent).

jsonencode({name = "example", count = 3})
jsondecode('{"name":"example"}')

Encode/decode JSON.

yamlencode({name = "example"})
yamldecode("name: example")

Encode/decode YAML.

base64encode("hello")
base64decode("aGVsbG8=")

Encode/decode Base64.

urlencode("hello world")
# "hello+world"

URL-encode string.

file("${path.module}/config.txt")

Read file contents as string.

filebase64("image.png")

Read file contents as base64.

templatefile("${path.module}/template.tpl", {
  name = "example"
  port = 8080
})

Render template file with variables.

basename("/path/to/file.txt")  # "file.txt"
dirname("/path/to/file.txt")   # "/path/to"

Extract filename or directory path.

abspath("./relative/path")

Convert relative to absolute path.

tostring(42)   # "42"
tonumber("42") # 42

Convert to string or number.

tobool("true")  # true

Convert string to boolean.

tolist(["a", "b"])
toset(["a", "b", "a"])  # ["a", "b"]

Convert to list or set (removes duplicates).

tomap({a = 1})

Convert to map type.

timestamp()
# "2024-01-15T10:30:00Z"

Current timestamp in UTC.

formatdate("YYYY-MM-DD", timestamp())

Format timestamp string.

timeadd(timestamp(), "24h")

Add duration to timestamp.

# Include parent config
include "root" {
  path = find_in_parent_folders()
}

# Local values
locals {
  environment = "prod"
  region      = "us-east-1"
}

# Terraform source
terraform {
  source = "git::git@github.com:example/modules.git//vpc?ref=v1.0.0"
}

Terragrunt extends Terraform with DRY configuration and dependency management.

remote_state {
  backend = "s3"
  config = {
    bucket = "my-terraform-state"
    key    = "${path_relative_to_include()}/terraform.tfstate"
    region = "us-east-1"
  }
}

Configure remote state backend.

dependency "vpc" {
  config_path = "../vpc"
}

inputs = {
  vpc_id = dependency.vpc.outputs.vpc_id
}

Declare dependencies on other Terragrunt modules.

generate "provider" {
  path      = "provider.tf"
  if_exists = "overwrite_terragrunt"
  contents  = <<EOF
provider "aws" {
  region = "${local.region}"
}
EOF
}

Generate files before running Terraform.

find_in_parent_folders("root.hcl")
path_relative_to_include()
get_terragrunt_dir()
get_parent_terragrunt_dir()
get_aws_account_id()
run_cmd("echo", "hello")

Terragrunt-specific helper functions.

terraform init
terraform validate
terraform fmt
terraform plan
terraform apply
terraform apply -auto-approve
terraform destroy

Standard workflow commands.

terraform plan -out=plan.tfplan
terraform apply plan.tfplan

Save plan to file for later apply.

terraform state list
terraform state show aws_instance.example
terraform state mv aws_instance.old aws_instance.new
terraform state rm aws_instance.example

Inspect and manipulate state.

terraform state pull > terraform.tfstate
terraform state push terraform.tfstate

Pull/push state manually.

terraform import aws_instance.example i-1234567890abcdef0
terraform import module.vpc.aws_vpc.main vpc-12345

Import existing infrastructure into state.

terraform workspace list
terraform workspace new dev
terraform workspace select prod
terraform workspace show
terraform workspace delete dev

Manage multiple named states.

terraform console
terraform graph | dot -Tpng > graph.png
terraform providers
terraform version
terraform test

Additional utility commands.

• Cannot use both count and for_each in same block
• lifecycle configurations affect dependency graph
• ignore_changes = all prevents all updates
• prevent_destroy doesn't work if resource removed from config

• For expressions with sets have no guaranteed order
• Splat [*] only works with lists, use for expression for maps

• Heredoc strings don't support backslash escapes
• Use $${ and %%{ to escape interpolation in heredocs

• Sensitive variables still stored in plaintext state
• State files may contain secrets - encrypt and restrict access

• Dynamic blocks can make code hard to read - use sparingly
• Cannot use dynamic blocks for lifecycle or provisioner blocks