Mastering HCL: Terraform's Configuration Language

My journey from basic syntax to advanced HCL patterns that make infrastructure elegant

Introduction: The Day I Discovered HCL's True Power

I was three months into using Terraform, and my configurations were working but ugly. Really ugly. Lots of repetition, hardcoded values, and what I call "infrastructure spaghetti."

Then I saw a senior engineer's Terraform code. It was beautiful. Dynamic, elegant, with no repetition. One configuration that handled 20 different scenarios with conditional logic, loops, and computed values.

"How did you do this?" I asked.

"HCL," they said. "You're barely scratching the surface."

They were right. I'd been using Terraform like a templating engine when it was actually a powerful programming language. That conversation sent me down a rabbit hole of learning HCL's advanced features: for expressions, dynamic blocks, conditional logic, and the 50+ built-in functions.

This article is everything I wish someone had taught me on day one. We're going deep into HashiCorp Configuration Language to transform your Terraform code from basic to elegant.

What is HCL?

HCL (HashiCorp Configuration Language) is Terraform's native configuration language. It's designed to be:

Human-readable - Looks like configuration, not code
Declarative - Describe what you want, not how to create it
Expressive - Powerful enough for complex scenarios
Consistent - Same syntax across all HashiCorp tools

HCL vs JSON vs YAML

# HCL - Native Terraform syntax
resource "local_file" "example" {
  filename = "hello.txt"
  content  = "Hello, ${var.name}!"
  
  lifecycle {
    create_before_destroy = true
  }
}

// JSON - Terraform supports it but it's verbose
{
  "resource": {
    "local_file": {
      "example": {
        "filename": "hello.txt",
        "content": "Hello, ${var.name}!",
        "lifecycle": {
          "create_before_destroy": true
        }
      }
    }
  }
}

# YAML - NOT supported by Terraform
# (Many people ask why, HCL is better for this use case)
resource:
  local_file:
    example:
      filename: hello.txt
      content: "Hello, ${var.name}!"

Why HCL wins:

Comments are better (# and // supported)
String interpolation built-in
Better support for expressions
More readable for infrastructure definitions

HCL Syntax Fundamentals

Let's master the building blocks of HCL.

Blocks

# Block structure
block_type "label" "name" {
  # Arguments
  key = value
  
  # Nested blocks
  nested_block {
    argument = "value"
  }
}

Examples:

# Resource block
resource "local_file" "config" {
  filename = "app.conf"
  content  = "data"
}

# Variable block
variable "environment" {
  type    = string
  default = "dev"
}

# Terraform block
terraform {
  required_version = ">= 1.0"
}

# Locals block
locals {
  timestamp = formatdate("YYYY-MM-DD", timestamp())
}

Arguments

# Simple assignment
filename = "config.txt"

# Expression assignment
port = var.base_port + 1000

# Function call
timestamp = timestamp()

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

# Map
tags = {
  Environment = "production"
  Team        = "platform"
}

Comments

# This is a line comment

// This is also a line comment

/* This is a
   multi-line comment */

resource "local_file" "example" {
  filename = "test.txt"  # Inline comment
  content  = "data"
}

Expressions and References

Expressions are how you compute values in HCL.

Simple Expressions

# Literal values
number = 42
string = "hello"
bool   = true

# Arithmetic
sum        = 10 + 5
difference = 100 - 25
product    = 4 * 3
quotient   = 10 / 2
modulo     = 10 % 3

# Comparison
is_equal        = 5 == 5     # true
is_not_equal    = 5 != 3     # true
greater_than    = 10 > 5     # true
less_than_equal = 5 <= 5     # true

# Logical
and_operation = true && false   # false
or_operation  = true || false   # true
not_operation = !true           # false

References

# Variable reference
var.environment
var.database.host
var.servers[0]

# Resource reference
local_file.config.filename
random_string.id.result

# Local value reference
local.environment_name
local.full_url

# Data source reference
data.local_file.existing.content

# Module output reference
module.networking.vpc_id

Attribute Access

# Dot notation
var.database.host
var.database.port

# Index notation
var.servers[0]
var.servers[count.index]

# Splat (all items)
local_file.configs[*].filename

String Templates and Interpolation

HCL's string interpolation is powerful and flexible.

Basic Interpolation

variable "name" {
  default = "Terraform"
}

resource "local_file" "greeting" {
  filename = "hello.txt"
  content  = "Hello, ${var.name}!"
}

Multi-line Strings (Heredoc)

resource "local_file" "config" {
  filename = "app.conf"
  
  content = <<-EOT
    application:
      name: ${var.app_name}
      port: ${var.port}
      environment: ${var.environment}
    
    database:
      host: ${var.db_host}
      port: ${var.db_port}
  EOT
}

String Directives

Interpolation directive:

content = <<-EOT
  Server count: ${length(var.servers)}
  First server: ${var.servers[0]}
EOT

Strip whitespace directive:

content = <<-EOT
  %{~ if var.enable_ssl ~}
  SSL: enabled
  %{~ else ~}
  SSL: disabled
  %{~ endif ~}
EOT
# ~~ removes newlines and whitespace

Conditional directive:

content = <<-EOT
  Environment: ${var.environment}
  %{ if var.environment == "production" }
  ⚠️  PRODUCTION ENVIRONMENT
  %{ endif }
EOT

Loop directive:

content = <<-EOT
  Servers:
  %{ for server in var.servers }
  - ${server.name}: ${server.ip}
  %{ endfor }
EOT

Template Functions

locals {
  # Join strings
  servers = join(", ", var.server_names)
  
  # Format string
  version = format("v%s.%s.%s", var.major, var.minor, var.patch)
  
  # Replace in string
  clean_name = replace(var.name, "/[^a-z0-9]/", "-")
  
  # Trim whitespace
  trimmed = trimspace("  hello  ")
  
  # Case conversion
  upper = upper(var.environment)
  lower = lower(var.region)
  title = title(var.name)
}

Conditional Expressions

Terraform's ternary operator enables conditional logic.

Basic Conditional

# Syntax: condition ? true_value : false_value

resource "local_file" "config" {
  filename = "config.txt"
  content  = var.environment == "production" ? "PROD CONFIG" : "DEV CONFIG"
}

Conditional Resource Creation

variable "create_backup" {
  type    = bool
  default = false
}

resource "local_file" "backup" {
  count = var.create_backup ? 1 : 0
  
  filename = "backup.txt"
  content  = "Backup file"
}

Nested Conditionals

locals {
  log_level = (
    var.environment == "production" ? "error" :
    var.environment == "staging" ? "warn" :
    "debug"
  )
  
  port = (
    var.environment == "production" ? 8080 :
    var.environment == "staging" ? 8081 :
    3000
  )
}

Conditional with Complex Logic

locals {
  # Multiple conditions
  enable_feature = var.environment == "production" && var.feature_flag == true
  
  # With default
  database_size = (
    var.tier == "enterprise" ? "xlarge" :
    var.tier == "professional" ? "large" :
    var.tier == "starter" ? "small" :
    "medium"  # default
  )
}

For Expressions

For expressions transform lists and maps. They're incredibly powerful.

List Transformation

Basic for loop:

variable "environments" {
  default = ["dev", "staging", "prod"]
}

locals {
  # Transform to uppercase
  upper_envs = [for env in var.environments : upper(env)]
  # Result: ["DEV", "STAGING", "PROD"]
  
  # Create filenames
  config_files = [for env in var.environments : "${env}-config.txt"]
  # Result: ["dev-config.txt", "staging-config.txt", "prod-config.txt"]
}

With conditionals:

locals {
  # Filter production environments
  prod_envs = [for env in var.environments : env if env == "prod"]
  
  # Transform and filter
  important_configs = [
    for env in var.environments : "${env}-config.txt"
    if env != "dev"
  ]
  # Result: ["staging-config.txt", "prod-config.txt"]
}

With index:

resource "local_file" "configs" {
  for_each = toset(var.environments)
  
  filename = "${each.key}-config.txt"
  content  = "Environment: ${each.value}"
}

Map Transformation

Create map from list:

variable "servers" {
  default = ["web1", "web2", "web3"]
}

locals {
  # List to map
  server_configs = {
    for server in var.servers : server => {
      hostname = "${server}.example.com"
      port     = 8080
    }
  }
  
  # Result:
  # {
  #   "web1" = { hostname = "web1.example.com", port = 8080 }
  #   "web2" = { hostname = "web2.example.com", port = 8080 }
  #   "web3" = { hostname = "web3.example.com", port = 8080 }
  # }
}

Transform map:

variable "instance_types" {
  default = {
    web = "t3.small"
    api = "t3.medium"
    db  = "t3.large"
  }
}

locals {
  # Transform map values
  uppercase_types = {
    for k, v in var.instance_types : k => upper(v)
  }
  
  # Filter map
  small_instances = {
    for k, v in var.instance_types : k => v
    if v == "t3.small"
  }
}

Complex map transformation:

variable "applications" {
  default = {
    web = { port = 80, replicas = 3 }
    api = { port = 8080, replicas = 5 }
    admin = { port = 9000, replicas = 1 }
  }
}

locals {
  # Create comprehensive config
  app_configs = {
    for name, config in var.applications : name => {
      url      = "https://${name}.example.com:${config.port}"
      replicas = config.replicas
      ha       = config.replicas > 1 ? "enabled" : "disabled"
    }
  }
}

Nested For Expressions

variable "regions" {
  default = {
    us-east-1 = ["a", "b", "c"]
    us-west-2 = ["a", "b"]
  }
}

locals {
  # Flatten nested structure
  all_zones = flatten([
    for region, zones in var.regions : [
      for zone in zones : {
        region = region
        zone   = "${region}${zone}"
      }
    ]
  ])
  
  # Result: [
  #   { region = "us-east-1", zone = "us-east-1a" },
  #   { region = "us-east-1", zone = "us-east-1b" },
  #   ...
  # ]
}

Splat Expressions

Splat expressions are shorthand for getting attributes from all items.

Basic Splat

resource "local_file" "configs" {
  count    = 3
  filename = "config-${count.index}.txt"
  content  = "Config ${count.index}"
}

# Get all filenames
output "all_files" {
  value = local_file.configs[*].filename
  # Same as: [for f in local_file.configs : f.filename]
}

Splat with for_each

resource "local_file" "envs" {
  for_each = toset(["dev", "staging", "prod"])
  
  filename = "${each.key}.txt"
  content  = "Environment: ${each.value}"
}

# Get all values
output "all_env_files" {
  value = values(local_file.envs)[*].filename
}

Conditional Splat

locals {
  # Get specific attribute from resources
  prod_files = [
    for f in local_file.configs[*] : f.filename
    if can(regex("prod", f.filename))
  ]
}

Local Values

Locals let you define named computed values that can be reused.

Basic Locals

locals {
  # Simple computed value
  environment_tag = upper(var.environment)
  
  # Timestamp
  deployment_time = timestamp()
  
  # Combination
  full_name = "${var.project_name}-${var.environment}"
}

resource "local_file" "config" {
  filename = "${local.full_name}-config.txt"
  content  = "Deployed at: ${local.deployment_time}"
}

Complex Locals

locals {
  # Common tags for all resources
  common_tags = {
    Environment = var.environment
    Project     = var.project_name
    ManagedBy   = "Terraform"
    DeployedAt  = formatdate("YYYY-MM-DD hh:mm:ss ZZZ", timestamp())
  }
  
  # Merge with environment-specific tags
  all_tags = merge(
    local.common_tags,
    var.environment == "production" ? {
      Compliance = "required"
      Backup     = "enabled"
    } : {}
  )
  
  # Configuration based on environment
  config = {
    port    = var.environment == "production" ? 8080 : 3000
    workers = var.environment == "production" ? 8 : 2
    cache   = var.environment == "production" ? true : false
  }
}

Locals Referencing Locals

locals {
  # Base values
  base_name = var.project_name
  env_suffix = var.environment
  
  # Build on base values
  full_name = "${local.base_name}-${local.env_suffix}"
  
  # Build on computed values
  config_filename = "${local.full_name}-config.yaml"
  secrets_filename = "${local.full_name}-secrets.json"
  
  # Complex computation
  deployment_config = {
    name      = local.full_name
    config    = local.config_filename
    secrets   = local.secrets_filename
    timestamp = timestamp()
  }
}

Built-in Functions

Terraform has 100+ built-in functions. Let's explore the most useful ones.

String Functions

locals {
  # Format string
  version = format("v%d.%d.%d", 1, 2, 3)  # "v1.2.3"
  
  # Join list to string
  servers = join(", ", ["web1", "web2", "web3"])  # "web1, web2, web3"
  
  # Split string to list
  parts = split("-", "blog-platform-prod")  # ["blog", "platform", "prod"]
  
  # Replace
  clean = replace("hello_world", "_", "-")  # "hello-world"
  
  # Regex replace
  alphanumeric = replace("test@123!", "/[^a-zA-Z0-9]/", "")  # "test123"
  
  # Trim
  trimmed = trimspace("  hello  ")  # "hello"
  trim_left = trimsuffix("hello.txt", ".txt")  # "hello"
  trim_right = trimprefix("mr-smith", "mr-")  # "smith"
  
  # Case conversion
  upper = upper("hello")  # "HELLO"
  lower = lower("HELLO")  # "hello"
  title = title("hello world")  # "Hello World"
  
  # Substring
  first_3 = substr("hello", 0, 3)  # "hel"
  
  # String length
  length = length("hello")  # 5
  
  # Contains
  has_prod = strcontains("production", "prod")  # true
}

Numeric Functions

locals {
  # Absolute value
  abs_value = abs(-5)  # 5
  
  # Ceiling and floor
  ceiling = ceil(4.3)  # 5
  floor = floor(4.8)  # 4
  
  # Min and max
  minimum = min(1, 2, 3, 4)  # 1
  maximum = max(1, 2, 3, 4)  # 4
  
  # Power
  squared = pow(3, 2)  # 9
  
  # Logarithm
  log_value = log(100, 10)  # 2
  
  # Parse number
  num = parseint("42", 10)  # 42
}

Collection Functions

locals {
  # Length
  list_length = length(["a", "b", "c"])  # 3
  map_length = length({a = 1, b = 2})  # 2
  
  # Element (get by index)
  second = element(["a", "b", "c"], 1)  # "b"
  
  # Index (find position)
  position = index(["a", "b", "c"], "b")  # 1
  
  # Contains
  has_item = contains(["a", "b", "c"], "b")  # true
  
  # Concat lists
  combined = concat(["a", "b"], ["c", "d"])  # ["a", "b", "c", "d"]
  
  # Distinct (remove duplicates)
  unique = distinct(["a", "b", "a", "c"])  # ["a", "b", "c"]
  
  # Flatten nested lists
  flat = flatten([["a", "b"], ["c", "d"]])  # ["a", "b", "c", "d"]
  
  # Reverse
  reversed = reverse(["a", "b", "c"])  # ["c", "b", "a"]
  
  # Slice (sublist)
  subset = slice(["a", "b", "c", "d"], 1, 3)  # ["b", "c"]
  
  # Sort
  sorted = sort(["c", "a", "b"])  # ["a", "b", "c"]
  
  # Range
  numbers = range(5)  # [0, 1, 2, 3, 4]
  custom_range = range(2, 8, 2)  # [2, 4, 6]
  
  # Compact (remove empty strings)
  no_empty = compact(["a", "", "b", ""])  # ["a", "b"]
}

Map Functions

locals {
  base_tags = {
    Environment = "dev"
    Project     = "blog"
  }
  
  extra_tags = {
    Team = "platform"
    Owner = "devops"
  }
  
  # Merge maps
  all_tags = merge(local.base_tags, local.extra_tags)
  
  # Keys and values
  tag_keys = keys(local.all_tags)  # ["Environment", "Project", "Team", "Owner"]
  tag_values = values(local.all_tags)  # ["dev", "blog", "platform", "devops"]
  
  # Lookup (get value by key)
  env = lookup(local.base_tags, "Environment", "default")  # "dev"
  missing = lookup(local.base_tags, "Missing", "default")  # "default"
  
  # Zip (combine two lists into map)
  servers = ["web1", "web2"]
  ips = ["10.0.1.10", "10.0.1.11"]
  server_ips = zipmap(local.servers, local.ips)
  # { web1 = "10.0.1.10", web2 = "10.0.1.11" }
}

Encoding Functions

locals {
  # JSON
  json_string = jsonencode({
    name = "blog"
    port = 8080
  })
  
  json_object = jsondecode("{\"name\":\"blog\"}")
  
  # YAML
  yaml_string = yamlencode({
    application = {
      name = "blog"
      port = 8080
    }
  })
  
  yaml_object = yamldecode("name: blog\nport: 8080")
  
  # Base64
  encoded = base64encode("hello")
  decoded = base64decode("aGVsbG8=")
  
  # URL encoding
  url_encoded = urlencode("hello world")  # "hello+world"
}

Filesystem Functions

locals {
  # Read file
  config_content = file("${path.module}/config.yaml")
  
  # Template file
  rendered = templatefile("${path.module}/template.tpl", {
    name = "blog"
    port = 8080
  })
  
  # File paths
  module_path = path.module
  root_path = path.root
  current_path = path.cwd
  
  # File exists
  has_config = fileexists("${path.module}/config.yaml")
  
  # File MD5/SHA
  config_md5 = filemd5("${path.module}/config.yaml")
  config_sha256 = filesha256("${path.module}/config.yaml")
  
  # Directory listing
  files = fileset(path.module, "*.tf")
}

Date and Time Functions

locals {
  # Current timestamp
  now = timestamp()  # "2025-12-31T10:30:45Z"
  
  # Format date
  formatted = formatdate("DD MMM YYYY hh:mm ZZZ", timestamp())
  # "31 Dec 2025 10:30 UTC"
  
  # Custom format
  iso_date = formatdate("YYYY-MM-DD", timestamp())  # "2025-12-31"
  time_only = formatdate("hh:mm:ss", timestamp())  # "10:30:45"
  
  # Timeadd (add duration)
  tomorrow = timeadd(timestamp(), "24h")
  next_week = timeadd(timestamp(), "168h")
}

Type Conversion Functions

locals {
  # To string
  str = tostring(42)  # "42"
  
  # To number
  num = tonumber("42")  # 42
  
  # To bool
  bool_val = tobool("true")  # true
  
  # To list
  list_val = tolist([1, 2, 3])
  
  # To set
  set_val = toset(["a", "b", "a"])  # {"a", "b"}
  
  # To map
  map_val = tomap({a = 1, b = 2})
  
  # Try (attempt conversion, return default on failure)
  safe_num = try(tonumber(var.input), 0)
}

Advanced Functions

locals {
  # Can (test if expression is valid)
  valid_json = can(jsondecode(var.config))
  valid_regex = can(regex("^[a-z]+$", var.name))
  
  # Coalesce (first non-null value)
  value = coalesce(var.override, var.default, "fallback")
  
  # Coalescelist (first non-empty list)
  list = coalescelist(var.custom_list, var.default_list, ["fallback"])
  
  # Sensitive (mark value as sensitive)
  secret = sensitive("password123")
  
  # Nonsensitive (unmark sensitive value)
  revealed = nonsensitive(var.password)
}

Dynamic Blocks

Dynamic blocks generate repeated nested blocks.

Basic Dynamic Block

Without dynamic (repetitive):

resource "null_resource" "example" {
  provisioner "local-exec" {
    command = "echo one"
  }
  
  provisioner "local-exec" {
    command = "echo two"
  }
  
  provisioner "local-exec" {
    command = "echo three"
  }
}

With dynamic (elegant):

variable "commands" {
  default = ["echo one", "echo two", "echo three"]
}

resource "null_resource" "example" {
  dynamic "provisioner" {
    for_each = var.commands
    content {
      local-exec {
        command = provisioner.value
      }
    }
  }
}

Complex Dynamic Blocks

Security group rules example:

variable "ingress_rules" {
  default = [
    { port = 80, protocol = "tcp", cidr = ["0.0.0.0/0"] },
    { port = 443, protocol = "tcp", cidr = ["0.0.0.0/0"] },
    { port = 22, protocol = "tcp", cidr = ["10.0.0.0/8"] }
  ]
}

# Note: This is conceptual - showing the pattern
resource "example_security_group" "web" {
  name = "web-sg"
  
  dynamic "ingress" {
    for_each = var.ingress_rules
    content {
      from_port   = ingress.value.port
      to_port     = ingress.value.port
      protocol    = ingress.value.protocol
      cidr_blocks = ingress.value.cidr
    }
  }
}

Nested Dynamic Blocks

variable "features" {
  default = {
    web = {
      enabled = true
      ports = [80, 443]
    }
    api = {
      enabled = true
      ports = [8080, 8443]
    }
  }
}

# Conceptual example
resource "example_resource" "app" {
  dynamic "feature" {
    for_each = { for k, v in var.features : k => v if v.enabled }
    content {
      name = feature.key
      
      dynamic "port" {
        for_each = feature.value.ports
        content {
          number = port.value
        }
      }
    }
  }
}

Conditional Dynamic Blocks

variable "enable_monitoring" {
  type    = bool
  default = false
}

resource "example_resource" "app" {
  # Only create monitoring block if enabled
  dynamic "monitoring" {
    for_each = var.enable_monitoring ? [1] : []
    content {
      enabled = true
      interval = 60
    }
  }
}

Complex Expression Patterns

Let's combine everything we've learned into advanced patterns.

Pattern 1: Environment-Specific Configuration

locals {
  # Environment-specific settings
  env_config = {
    dev = {
      instance_count = 1
      instance_size  = "small"
      backup_enabled = false
      monitoring     = "basic"
    }
    staging = {
      instance_count = 2
      instance_size  = "medium"
      backup_enabled = true
      monitoring     = "standard"
    }
    production = {
      instance_count = 5
      instance_size  = "large"
      backup_enabled = true
      monitoring     = "advanced"
    }
  }
  
  # Get current environment config
  current_config = local.env_config[var.environment]
  
  # Computed values based on environment
  log_level = var.environment == "production" ? "warn" : "debug"
  cache_ttl = var.environment == "production" ? 3600 : 300
}

Pattern 2: Resource Naming Convention

locals {
  # Naming convention: {project}-{environment}-{resource}-{identifier}
  resource_prefix = "${var.project_name}-${var.environment}"
  
  # Generate resource names
  resource_names = {
    for resource_type in ["web", "api", "db", "cache"] :
    resource_type => "${local.resource_prefix}-${resource_type}"
  }
  
  # With sanitization
  safe_name = lower(replace(local.resource_prefix, "/[^a-z0-9-]/", "-"))
}

Pattern 3: Tag Standardization

locals {
  # Base tags for all resources
  base_tags = {
    Project     = var.project_name
    Environment = var.environment
    ManagedBy   = "Terraform"
    DeployedAt  = formatdate("YYYY-MM-DD", timestamp())
    Owner       = var.team_name
  }
  
  # Environment-specific tags
  env_tags = var.environment == "production" ? {
    Compliance   = "required"
    BackupPolicy = "daily"
    Monitoring   = "24x7"
  } : {}
  
  # Cost allocation tags
  cost_tags = {
    CostCenter = var.cost_center
    BillingID  = "${var.project_name}-${var.environment}"
  }
  
  # Merge all tags
  standard_tags = merge(
    local.base_tags,
    local.env_tags,
    local.cost_tags,
    var.custom_tags
  )
}

Pattern 4: Feature Flags with Validation

variable "features" {
  type = map(object({
    enabled     = bool
    min_tier    = string
    dependencies = list(string)
  }))
  
  default = {
    caching = {
      enabled      = true
      min_tier     = "basic"
      dependencies = []
    }
    analytics = {
      enabled      = true
      min_tier     = "professional"
      dependencies = ["caching"]
    }
    cdn = {
      enabled      = true
      min_tier     = "enterprise"
      dependencies = ["caching", "analytics"]
    }
  }
}

locals {
  # Check if tier supports features
  tier_level = {
    basic        = 1
    professional = 2
    enterprise   = 3
  }
  
  current_tier_level = local.tier_level[var.tier]
  
  # Filter features by tier and enabled status
  available_features = {
    for name, config in var.features :
    name => config
    if config.enabled && local.tier_level[config.min_tier] <= local.current_tier_level
  }
  
  # Validate dependencies
  enabled_feature_names = keys(local.available_features)
  
  # List of actually enabled features
  active_features = [
    for name, config in local.available_features :
    name
    if alltrue([
      for dep in config.dependencies :
      contains(local.enabled_feature_names, dep)
    ])
  ]
}

Real-World Example: Advanced Blog Platform

Let's build a sophisticated blog platform using advanced HCL.

Project Structure

advanced-blog/
├── main.tf
├── variables.tf
├── locals.tf
├── outputs.tf
└── environments/
    ├── dev.tfvars
    ├── staging.tfvars
    └── production.tfvars

variables.tf

variable "environment" {
  type = string
  validation {
    condition     = contains(["dev", "staging", "production"], var.environment)
    error_message = "Must be dev, staging, or production."
  }
}

variable "project" {
  type = object({
    name        = string
    version     = string
    team        = string
    cost_center = string
  })
}

variable "services" {
  type = map(object({
    enabled  = bool
    replicas = number
    port     = number
    features = list(string)
  }))
}

variable "feature_flags" {
  type = map(bool)
}

locals.tf

locals {
  # Environment configuration matrix
  env_matrix = {
    dev = {
      tier            = "basic"
      scale_factor    = 1
      log_level       = "debug"
      cache_enabled   = false
      backup_enabled  = false
      monitoring_tier = "basic"
    }
    staging = {
      tier            = "professional"
      scale_factor    = 2
      log_level       = "info"
      cache_enabled   = true
      backup_enabled  = true
      monitoring_tier = "standard"
    }
    production = {
      tier            = "enterprise"
      scale_factor    = 5
      log_level       = "warn"
      cache_enabled   = true
      backup_enabled  = true
      monitoring_tier = "advanced"
    }
  }
  
  # Current environment settings
  env = local.env_matrix[var.environment]
  
  # Resource naming
  prefix = "${var.project.name}-${var.environment}"
  safe_prefix = lower(replace(local.prefix, "/[^a-z0-9-]/", "-"))
  
  # Timestamp utilities
  deployment_timestamp = timestamp()
  deployment_date = formatdate("YYYY-MM-DD", local.deployment_timestamp)
  deployment_id = substr(sha256(local.deployment_timestamp), 0, 8)
  
  # Standard tags
  tags = merge(
    {
      Project       = var.project.name
      Version       = var.project.version
      Environment   = var.environment
      Team          = var.project.team
      CostCenter    = var.project.cost_center
      ManagedBy     = "Terraform"
      DeployedAt    = local.deployment_date
      DeploymentID  = local.deployment_id
    },
    var.environment == "production" ? {
      Compliance    = "required"
      BackupPolicy  = "daily"
      DisasterRecovery = "enabled"
    } : {}
  )
  
  # Service configuration
  enabled_services = {
    for name, config in var.services :
    name => merge(config, {
      replicas_scaled = config.replicas * local.env.scale_factor
      full_name      = "${local.safe_prefix}-${name}"
      endpoint       = "${name}.${var.environment}.${var.project.name}.local"
    })
    if config.enabled
  }
  
  # Generate port mappings
  port_mappings = {
    for name, service in local.enabled_services :
    name => {
      internal = service.port
      external = service.port + (var.environment == "production" ? 0 : 1000)
    }
  }
  
  # Feature matrix
  features = {
    for feature, enabled in var.feature_flags :
    feature => {
      enabled = enabled
      available_in_tier = contains(
        ["professional", "enterprise"],
        local.env.tier
      ) || feature == "basic_auth"
    }
  }
  
  # Enabled features (respecting tier limits)
  active_features = [
    for feature, config in local.features :
    feature
    if config.enabled && config.available_in_tier
  ]
  
  # Service dependencies
  service_graph = {
    for name, service in local.enabled_services :
    name => {
      depends_on = [
        for feature in service.features :
        feature if contains(local.active_features, feature)
      ]
    }
  }
}

main.tf

terraform {
  required_version = ">= 1.0"
  required_providers {
    random = { source = "hashicorp/random", version = "~> 3.5" }
    local  = { source = "hashicorp/local", version = "~> 2.4" }
  }
}

# Generate unique deployment ID
resource "random_uuid" "deployment" {}

# Generate service secrets
resource "random_password" "service_secrets" {
  for_each = local.enabled_services
  
  length  = 32
  special = true
}

# Create service configurations
resource "local_file" "service_configs" {
  for_each = local.enabled_services
  
  filename = "${path.module}/generated/${var.environment}/config/${each.key}.yaml"
  
  content = yamlencode({
    service = {
      name        = each.value.full_name
      version     = var.project.version
      environment = var.environment
      replicas    = each.value.replicas_scaled
    }
    
    network = {
      port     = local.port_mappings[each.key].internal
      endpoint = each.value.endpoint
    }
    
    features = {
      enabled = [
        for feature in each.value.features :
        feature if contains(local.active_features, feature)
      ]
      
      caching    = local.env.cache_enabled
      monitoring = local.env.monitoring_tier
    }
    
    security = {
      secret_file = "./secrets/${each.key}.txt"
    }
    
    logging = {
      level = local.env.log_level
      format = var.environment == "production" ? "json" : "text"
    }
    
    tags = local.tags
  })
  
  file_permission = "0644"
}

# Create service secrets
resource "local_file" "service_secrets" {
  for_each = local.enabled_services
  
  filename        = "${path.module}/generated/${var.environment}/secrets/${each.key}.txt"
  content         = random_password.service_secrets[each.key].result
  file_permission = "0600"
}

# Create deployment manifest
resource "local_file" "deployment_manifest" {
  filename = "${path.module}/generated/${var.environment}/deployment.yaml"
  
  content = yamlencode({
    deployment = {
      id          = random_uuid.deployment.result
      timestamp   = local.deployment_timestamp
      environment = var.environment
      tier        = local.env.tier
    }
    
    project = var.project
    
    services = {
      for name, service in local.enabled_services :
      name => {
        enabled   = true
        replicas  = service.replicas_scaled
        port      = local.port_mappings[name].internal
        endpoint  = service.endpoint
        features  = service.features
      }
    }
    
    features = {
      active = local.active_features
      matrix = local.features
    }
    
    tags = local.tags
  })
  
  file_permission = "0644"
}

# Create docker-compose file using dynamic blocks
resource "local_file" "docker_compose" {
  filename = "${path.module}/generated/${var.environment}/docker-compose.yaml"
  
  content = yamlencode({
    version = "3.8"
    
    services = {
      for name, service in local.enabled_services :
      name => {
        image = "${var.project.name}/${name}:${var.project.version}"
        
        ports = [
          "${local.port_mappings[name].external}:${local.port_mappings[name].internal}"
        ]
        
        environment = {
          SERVICE_NAME = service.full_name
          ENVIRONMENT  = var.environment
          LOG_LEVEL    = local.env.log_level
          REPLICAS     = tostring(service.replicas_scaled)
        }
        
        volumes = [
          "./config/${name}.yaml:/app/config.yaml:ro",
          "./secrets/${name}.txt:/app/secret.txt:ro"
        ]
        
        deploy = {
          replicas = service.replicas_scaled
        }
        
        labels = local.tags
      }
    }
  })
  
  file_permission = "0644"
}

# Create comprehensive README
resource "local_file" "readme" {
  filename = "${path.module}/generated/${var.environment}/README.md"
  
  content = <<-EOT
    # ${title(var.environment)} Environment - ${var.project.name}
    
    **Version**: ${var.project.version}  
    **Deployment ID**: ${random_uuid.deployment.result}  
    **Deployed**: ${local.deployment_date}  
    **Tier**: ${local.env.tier}
    
    ## Services
    
    ${join("\n", [
      for name, service in local.enabled_services :
      "### ${title(name)}\n- **Replicas**: ${service.replicas_scaled}\n- **Port**: ${local.port_mappings[name].external} → ${local.port_mappings[name].internal}\n- **Endpoint**: ${service.endpoint}\n- **Features**: ${join(", ", service.features)}"
    ])}
    
    ## Active Features
    
    ${join("\n", [for f in local.active_features : "- ✓ ${title(replace(f, "_", " "))}"])}
    
    ## Configuration Files
    
    - **Deployment Manifest**: `deployment.yaml`
    - **Docker Compose**: `docker-compose.yaml`
    - **Service Configs**: `config/*.yaml`
    - **Secrets**: `secrets/*.txt` (permissions: 0600)
    
    ## Quick Start
    
    ```bash
    # Start all services
    docker-compose up -d
    
    # View logs
    docker-compose logs -f
    
    # Stop all services
    docker-compose down
    ```
    
    ## Environment Details
    
    - **Tier**: ${local.env.tier}
    - **Scale Factor**: ${local.env.scale_factor}x
    - **Log Level**: ${local.env.log_level}
    - **Caching**: ${local.env.cache_enabled ? "Enabled" : "Disabled"}
    - **Backups**: ${local.env.backup_enabled ? "Enabled" : "Disabled"}
    - **Monitoring**: ${local.env.monitoring_tier}
    
    ## Tags
    
    ${join("\n", [for k, v in local.tags : "- **${k}**: ${v}"])}
  EOT
  
  file_permission = "0644"
}

environments/production.tfvars

environment = "production"

project = {
  name        = "blog-platform"
  version     = "2.5.0"
  team        = "platform-engineering"
  cost_center = "eng-001"
}

services = {
  web = {
    enabled  = true
    replicas = 3
    port     = 8080
    features = ["caching", "cdn", "analytics"]
  }
  
  api = {
    enabled  = true
    replicas = 5
    port     = 8081
    features = ["rate_limiting", "caching", "monitoring"]
  }
  
  admin = {
    enabled  = true
    replicas = 2
    port     = 9000
    features = ["audit_logging", "2fa"]
  }
  
  worker = {
    enabled  = true
    replicas = 3
    port     = 9001
    features = ["queue", "retry", "monitoring"]
  }
}

feature_flags = {
  caching        = true
  cdn            = true
  analytics      = true
  rate_limiting  = true
  monitoring     = true
  audit_logging  = true
  2fa            = true
  queue          = true
  retry          = true
  basic_auth     = false
}

Deploy

terraform init
terraform apply -var-file="environments/production.tfvars"

Common Mistakes and How to Avoid Them

Mistake #1: Overusing Ternary Operators

Bad:

locals {
  value = var.env == "prod" ? "a" : var.env == "staging" ? "b" : var.env == "dev" ? "c" : "d"
  # Unreadable!
}

Good:

locals {
  env_values = {
    prod    = "a"
    staging = "b"
    dev     = "c"
  }
  
  value = lookup(local.env_values, var.env, "d")
}

Mistake #2: Not Using Locals for Repeated Expressions

Bad:

resource "local_file" "config1" {
  content = "${var.project}-${var.environment}-${formatdate("YYYY-MM-DD", timestamp())}"
}

resource "local_file" "config2" {
  content = "${var.project}-${var.environment}-${formatdate("YYYY-MM-DD", timestamp())}"
}

Good:

locals {
  prefix = "${var.project}-${var.environment}-${formatdate("YYYY-MM-DD", timestamp())}"
}

resource "local_file" "config1" {
  content = local.prefix
}

resource "local_file" "config2" {
  content = local.prefix
}

Mistake #3: Incorrect For Expression Syntax

Bad:

locals {
  # Missing brackets
  upper = for s in var.list : upper(s)  # ERROR!
}

Good:

locals {
  upper = [for s in var.list : upper(s)]  # List
  
  # Or for map:
  upper_map = {for k, v in var.map : k => upper(v)}
}

Mistake #4: Trying to Use Variables in terraform {} Block

Bad:

variable "provider_version" {
  default = "~> 3.0"
}

terraform {
  required_providers {
    local = {
      version = var.provider_version  # ERROR! Can't use variables here
    }
  }
}

Good:

terraform {
  required_providers {
    local = {
      version = "~> 3.0"  # Must be literal
    }
  }
}

Mistake #5: Forgetting Type Conversions

Bad:

locals {
  count = "5"  # String
}

resource "local_file" "files" {
  count = local.count  # ERROR! Expects number
}

Good:

locals {
  count = tonumber("5")  # Convert to number
}

resource "local_file" "files" {
  count = local.count
}

Best Practices for HCL

1. Use Locals for Complex Expressions

# Good
locals {
  environment_config = {
    dev = { size = "small", replicas = 1 }
    prod = { size = "large", replicas = 5 }
  }
  
  current_config = local.environment_config[var.environment]
}

resource "example" "app" {
  size = local.current_config.size
}

2. Prefer Maps Over Nested Ternaries

# Instead of this
locals {
  size = var.env == "prod" ? "large" : var.env == "staging" ? "medium" : "small"
}

# Use this
locals {
  sizes = {
    prod    = "large"
    staging = "medium"
    dev     = "small"
  }
  
  size = local.sizes[var.env]
}

3. Use For Expressions for Transformations

# Good
locals {
  uppercase_names = [for name in var.names : upper(name)]
  
  service_ports = {
    for service, config in var.services :
    service => config.port
  }
}

4. Comment Complex Expressions

locals {
  # Calculate total capacity across all regions
  # Formula: sum(replicas * instance_size_multiplier)
  total_capacity = sum([
    for region, config in var.regions :
    config.replicas * local.size_multipliers[config.instance_size]
  ])
}

5. Extract Magic Numbers to Variables

# Bad
locals {
  timeout = 300  # What does 300 mean?
}

# Good
variable "default_timeout_seconds" {
  default = 300
  description = "Default timeout in seconds (5 minutes)"
}

locals {
  timeout = var.default_timeout_seconds
}

What I Learned About HCL Mastery

1. HCL is More Powerful Than It Looks

When I started, I thought HCL was just a configuration format. It's actually a full expression language with:

100+ built-in functions
List and map comprehensions
Conditional logic
Type system
Template rendering

2. Locals Are Your Best Friend

Locals let you:

Name complex expressions
Reuse computations
Document intent
Reduce duplication

Use them liberally!

3. For Expressions Replace Most Loops

Instead of creating resources with count or for_each, use for expressions to transform data first:

locals {
  # Transform data
  configs = {
    for env in var.environments :
    env => {
      replicas = env == "prod" ? 5 : 1
      size     = env == "prod" ? "large" : "small"
    }
  }
}

# Then use transformed data
resource "example" "app" {
  for_each = local.configs
  # ...
}

4. Functions Are Composable

Chain functions for powerful transformations:

locals {
  # Clean, uppercase, sort, join
  tags = join(", ", sort([
    for tag in split(",", var.raw_tags) :
    upper(trimspace(tag))
  ]))
}

5. Dynamic Blocks Are Last Resort

Use dynamic blocks only when necessary. Often there's a better way:

# Instead of dynamic block, use for_each
resource "example" "app" {
  for_each = var.ports
  
  port = each.value
}

Next Steps

Congratulations! You've mastered HCL:

✅ HCL syntax fundamentals ✅ Expressions and references ✅ String templates and interpolation ✅ Conditional expressions ✅ For expressions and splat ✅ Local values ✅ 100+ built-in functions ✅ Dynamic blocks ✅ Advanced blog platform with complex HCL

Practice Exercises

Exercise 1: For Expressions

# Transform this list into various formats
variable "servers" {
  default = ["web1", "web2", "api1", "db1"]
}

# Create:
# 1. Uppercase list
# 2. Map of server names to configs
# 3. Filtered list (only "web" servers)
# 4. List of server objects with properties

Exercise 2: Function Chaining

# Combine multiple functions to:
# 1. Take comma-separated string
# 2. Split into list
# 3. Trim whitespace from each
# 4. Convert to uppercase
# 5. Remove duplicates
# 6. Sort alphabetically
# 7. Join back to string

Exercise 3: Dynamic Configuration

# Build a configuration that:
# 1. Uses locals for environment matrix
# 2. Computes resource sizes based on tier
# 3. Generates service configurations
# 4. Creates deployment manifests

Coming Up Next

In Article 5: Modules - Building Reusable Infrastructure Components, we'll learn:

What modules are and why they matter
Creating custom modules
Module inputs and outputs
Module composition
Terraform Registry
Versioning and publishing modules

HCL is the language. Modules are how you organize that language into reusable, composable infrastructure components.

This Week's Challenge: Refactor your existing Terraform configurations to use for expressions, locals, and functions. Eliminate all code duplication. Make it elegant.

See you in Article 5! 🎨

"HCL transformed my Terraform from simple templating to elegant programming. The day I discovered for expressions and local values was the day my infrastructure code became beautiful." - Me, after refactoring 2,000 lines down to 400

PreviousVariables and Outputs: Making Infrastructure Reusable NextModules: Building Reusable Infrastructure Components

Last updated 1 month ago

hashtagTable of Contents

hashtagIntroduction: The Day I Discovered HCL's True Power

hashtagWhat is HCL?

hashtagHCL vs JSON vs YAML

hashtagHCL Syntax Fundamentals

hashtagBlocks

hashtagArguments

hashtagComments

hashtagExpressions and References

hashtagSimple Expressions

hashtagReferences

hashtagAttribute Access

hashtagString Templates and Interpolation

hashtagBasic Interpolation

hashtagMulti-line Strings (Heredoc)

hashtagString Directives

hashtagTemplate Functions

hashtagConditional Expressions

hashtagBasic Conditional

hashtagConditional Resource Creation

hashtagNested Conditionals

hashtagConditional with Complex Logic

hashtagFor Expressions

hashtagList Transformation

hashtagMap Transformation

hashtagNested For Expressions

hashtagSplat Expressions

hashtagBasic Splat

hashtagSplat with for_each

hashtagConditional Splat

hashtagLocal Values

hashtagBasic Locals

hashtagComplex Locals

hashtagLocals Referencing Locals

hashtagBuilt-in Functions

hashtagString Functions

hashtagNumeric Functions

hashtagCollection Functions

hashtagMap Functions

hashtagEncoding Functions

hashtagFilesystem Functions

hashtagDate and Time Functions

hashtagType Conversion Functions

hashtagAdvanced Functions

hashtagDynamic Blocks

hashtagBasic Dynamic Block

hashtagComplex Dynamic Blocks

hashtagNested Dynamic Blocks

hashtagConditional Dynamic Blocks

hashtagComplex Expression Patterns

hashtagPattern 1: Environment-Specific Configuration

hashtagPattern 2: Resource Naming Convention

hashtagPattern 3: Tag Standardization

hashtagPattern 4: Feature Flags with Validation

hashtagReal-World Example: Advanced Blog Platform

hashtagProject Structure

hashtagvariables.tf

hashtaglocals.tf

hashtagmain.tf

hashtagenvironments/production.tfvars

hashtagDeploy

hashtagCommon Mistakes and How to Avoid Them

hashtagMistake #1: Overusing Ternary Operators

hashtagMistake #2: Not Using Locals for Repeated Expressions

hashtagMistake #3: Incorrect For Expression Syntax

hashtagMistake #4: Trying to Use Variables in terraform {} Block

hashtagMistake #5: Forgetting Type Conversions

hashtagBest Practices for HCL

hashtag1. Use Locals for Complex Expressions

hashtag2. Prefer Maps Over Nested Ternaries

hashtag3. Use For Expressions for Transformations

hashtag4. Comment Complex Expressions

hashtag5. Extract Magic Numbers to Variables

hashtagWhat I Learned About HCL Mastery

hashtag1. HCL is More Powerful Than It Looks

hashtag2. Locals Are Your Best Friend

hashtag3. For Expressions Replace Most Loops

hashtag4. Functions Are Composable

hashtag5. Dynamic Blocks Are Last Resort

hashtagNext Steps

Table of Contents

Introduction: The Day I Discovered HCL's True Power

What is HCL?

HCL vs JSON vs YAML

HCL Syntax Fundamentals

Blocks

Arguments

Comments

Expressions and References

Simple Expressions

References

Attribute Access

String Templates and Interpolation

Basic Interpolation

Multi-line Strings (Heredoc)

String Directives

Template Functions

Conditional Expressions

Basic Conditional

Conditional Resource Creation

Nested Conditionals

Conditional with Complex Logic

For Expressions

List Transformation

Map Transformation

Nested For Expressions

Splat Expressions

Basic Splat

Splat with for_each

Conditional Splat

Local Values

Basic Locals

Complex Locals

Locals Referencing Locals

Built-in Functions

String Functions

Numeric Functions

Collection Functions

Map Functions

Encoding Functions

Filesystem Functions

Date and Time Functions

Type Conversion Functions

Advanced Functions

Dynamic Blocks

Basic Dynamic Block

Complex Dynamic Blocks

Nested Dynamic Blocks

Conditional Dynamic Blocks

Complex Expression Patterns

Pattern 1: Environment-Specific Configuration

Pattern 2: Resource Naming Convention

Pattern 3: Tag Standardization

Pattern 4: Feature Flags with Validation

Real-World Example: Advanced Blog Platform

Project Structure

variables.tf

locals.tf

main.tf

environments/production.tfvars

Deploy

Common Mistakes and How to Avoid Them

Mistake #1: Overusing Ternary Operators

Mistake #2: Not Using Locals for Repeated Expressions

Mistake #3: Incorrect For Expression Syntax

Mistake #4: Trying to Use Variables in terraform {} Block

Mistake #5: Forgetting Type Conversions

Best Practices for HCL

1. Use Locals for Complex Expressions

2. Prefer Maps Over Nested Ternaries

3. Use For Expressions for Transformations

4. Comment Complex Expressions

5. Extract Magic Numbers to Variables

What I Learned About HCL Mastery

1. HCL is More Powerful Than It Looks

2. Locals Are Your Best Friend

3. For Expressions Replace Most Loops

4. Functions Are Composable

5. Dynamic Blocks Are Last Resort

Next Steps