HCL (HashiCorp Configuration Language) File Format

Overview

The HCL (HashiCorp Configuration Language) format is a structured configuration language designed to be both human-readable and machine-parseable. Developed by HashiCorp, HCL is used across their tools including Terraform, Consul, Nomad, and Vault. It combines the readability of YAML with the expressiveness of JSON while adding unique features for infrastructure as code.

Technical Details

File Characteristics

• Extension: .hcl, .tf (Terraform), .nomad, .hcl2
• MIME Type: text/plain
• Category: Config
• Format Type: Structured configuration language

Design Principles

• Human-Readable: Easy to read and write
• Machine-Parseable: Efficient parsing and validation
• Hierarchical: Nested structure support
• Expressive: Variables, functions, and interpolation
• Extensible: Custom syntax for different tools

Basic Syntax

Key-Value Pairs

# Simple assignments
name = "example"
port = 8080
enabled = true
timeout = 30.5

# String values
description = "A sample configuration"
multiline = <<EOF
This is a multiline
string value that spans
multiple lines.
EOF

# Lists (arrays)
tags = ["web", "production", "us-east"]
ports = [80, 443, 8080]
mixed_list = ["string", 123, true]

# Maps (objects)
metadata = {
  environment = "production"
  owner       = "devops-team"
  cost_center = "engineering"
}

Blocks

# Basic block
resource "aws_instance" "example" {
  ami           = "ami-12345678"
  instance_type = "t3.micro"
  
  tags = {
    Name = "ExampleInstance"
  }
}

# Nested blocks
resource "aws_security_group" "web" {
  name_prefix = "web-"
  
  ingress {
    from_port   = 80
    to_port     = 80
    protocol    = "tcp"
    cidr_blocks = ["0.0.0.0/0"]
  }
  
  ingress {
    from_port   = 443
    to_port     = 443
    protocol    = "tcp"
    cidr_blocks = ["0.0.0.0/0"]
  }
  
  egress {
    from_port   = 0
    to_port     = 0
    protocol    = "-1"
    cidr_blocks = ["0.0.0.0/0"]
  }
}

# Multiple block labels
variable "instance_count" {
  description = "Number of instances to create"
  type        = number
  default     = 1
}

Comments

# Single line comment
// Alternative single line comment

/*
Multi-line comment
can span multiple lines
*/

# Inline comments
port = 8080 # This is the HTTP port

Variables and Interpolation

Variable Declarations

# Variable with default
variable "environment" {
  description = "Environment name"
  type        = string
  default     = "development"
}

# Variable with validation
variable "instance_type" {
  description = "EC2 instance type"
  type        = string
  default     = "t3.micro"
  
  validation {
    condition = contains([
      "t3.micro",
      "t3.small", 
      "t3.medium"
    ], var.instance_type)
    error_message = "Instance type must be t3.micro, t3.small, or t3.medium."
  }
}

# Complex variable types
variable "subnets" {
  description = "Subnet configuration"
  type = map(object({
    cidr_block        = string
    availability_zone = string
    public           = bool
  }))
  default = {
    public = {
      cidr_block        = "10.0.1.0/24"
      availability_zone = "us-west-2a"
      public           = true
    }
    private = {
      cidr_block        = "10.0.2.0/24"
      availability_zone = "us-west-2b" 
      public           = false
    }
  }
}

String Interpolation

# Variable interpolation
resource "aws_instance" "web" {
  ami           = var.ami_id
  instance_type = var.instance_type
  
  tags = {
    Name = "${var.project_name}-${var.environment}"
    Owner = var.owner
  }
}

# Expression interpolation
resource "aws_security_group_rule" "ssh" {
  from_port         = 22
  to_port           = 22
  protocol          = "tcp"
  cidr_blocks       = [for cidr in var.allowed_cidrs : cidr if cidr != ""]
  security_group_id = aws_security_group.main.id
}

# Function calls
locals {
  timestamp = formatdate("YYYY-MM-DD", timestamp())
  
  common_tags = {
    Project     = var.project_name
    Environment = var.environment
    CreatedAt   = local.timestamp
  }
}

Functions and Expressions

Built-in Functions

# String functions
locals {
  upper_name    = upper(var.project_name)
  trimmed       = trimspace(var.description)
  joined        = join("-", [var.project, var.environment])
  formatted     = format("instance-%03d", var.instance_number)
  replaced      = replace(var.name, "_", "-")
}

# Numeric functions
locals {
  absolute     = abs(var.offset)
  maximum      = max(var.cpu_limit, 100)
  minimum      = min(var.memory_limit, 512)
  rounded      = ceil(var.ratio * 100)
}

# Collection functions
locals {
  sorted_tags  = sort(var.tags)
  unique_ids   = distinct(var.instance_ids)
  key_list     = keys(var.metadata)
  value_list   = values(var.metadata)
  flattened    = flatten(var.nested_lists)
}

# Type conversion
locals {
  as_string = tostring(var.port)
  as_number = tonumber(var.count_string)
  as_bool   = tobool(var.enabled_string)
  as_list   = tolist(var.set_values)
  as_map    = tomap(var.object_values)
}

Conditional Expressions

# Ternary operator
resource "aws_instance" "web" {
  instance_type = var.environment == "production" ? "t3.large" : "t3.micro"
  
  monitoring = var.enable_monitoring ? true : false
  
  tags = {
    Name = var.environment == "production" ? "${var.name}-prod" : "${var.name}-dev"
  }
}

# Complex conditionals
locals {
  instance_count = (
    var.environment == "production" ? var.prod_instance_count :
    var.environment == "staging" ? var.staging_instance_count :
    1
  )
  
  storage_type = var.high_performance ? "gp3" : "gp2"
}

For Expressions

# List comprehension
locals {
  # Transform list
  uppercase_tags = [for tag in var.tags : upper(tag)]
  
  # Filter and transform
  public_subnets = [
    for subnet in var.subnets : subnet.id 
    if subnet.public == true
  ]
  
  # Create map from list
  tag_map = {
    for i, tag in var.tags : i => tag
  }
  
  # Transform map
  environment_configs = {
    for env, config in var.environments : env => {
      instance_type = config.high_performance ? "c5.large" : "t3.micro"
      storage_size  = config.storage_gb
      monitoring    = env == "production"
    }
  }
}

# Complex for expressions
locals {
  # Nested iteration
  all_subnet_routes = flatten([
    for vpc_name, vpc in var.vpcs : [
      for subnet_name, subnet in vpc.subnets : {
        vpc_name    = vpc_name
        subnet_name = subnet_name
        route_table = "${vpc_name}-${subnet_name}-rt"
      }
    ]
  ])
}

Advanced Features

Dynamic Blocks

# Dynamic ingress rules
resource "aws_security_group" "web" {
  name_prefix = "web-sg"
  
  dynamic "ingress" {
    for_each = var.ingress_ports
    
    content {
      from_port   = ingress.value.port
      to_port     = ingress.value.port
      protocol    = ingress.value.protocol
      cidr_blocks = ingress.value.cidr_blocks
      description = ingress.value.description
    }
  }
  
  dynamic "egress" {
    for_each = var.allow_all_outbound ? [1] : []
    
    content {
      from_port   = 0
      to_port     = 0
      protocol    = "-1"
      cidr_blocks = ["0.0.0.0/0"]
    }
  }
}

# Dynamic tags
resource "aws_instance" "web" {
  ami           = var.ami_id
  instance_type = var.instance_type
  
  dynamic "tag" {
    for_each = merge(var.default_tags, var.custom_tags)
    
    content {
      key   = tag.key
      value = tag.value
    }
  }
}

Local Values

# Complex local computations
locals {
  # Environment-specific settings
  env_config = {
    development = {
      instance_type = "t3.micro"
      min_size     = 1
      max_size     = 2
      storage_size = 20
    }
    staging = {
      instance_type = "t3.small"
      min_size     = 1
      max_size     = 3
      storage_size = 50
    }
    production = {
      instance_type = "t3.large"
      min_size     = 2
      max_size     = 10
      storage_size = 100
    }
  }
  
  # Current environment config
  current_config = local.env_config[var.environment]
  
  # Computed values
  total_storage = local.current_config.storage_size * var.instance_count
  
  # Common tags
  common_tags = {
    Environment   = var.environment
    Project      = var.project_name
    ManagedBy    = "terraform"
    CreatedAt    = timestamp()
  }
  
  # Resource naming
  name_prefix = "${var.project_name}-${var.environment}"
  
  # Network configuration
  vpc_cidr = "10.${var.vpc_number}.0.0/16"
  subnet_cidrs = [
    for i in range(var.subnet_count) : 
    cidrsubnet(local.vpc_cidr, 8, i)
  ]
}

Modules

# Module usage
module "vpc" {
  source = "./modules/vpc"
  
  vpc_cidr             = var.vpc_cidr
  availability_zones   = var.availability_zones
  public_subnet_cidrs  = var.public_subnet_cidrs
  private_subnet_cidrs = var.private_subnet_cidrs
  
  enable_nat_gateway = var.environment == "production"
  enable_vpn_gateway = var.enable_vpn
  
  tags = local.common_tags
}

module "database" {
  source = "terraform-aws-modules/rds/aws"
  version = "~> 5.0"
  
  identifier = "${local.name_prefix}-db"
  
  engine               = "postgresql"
  engine_version       = "14.9"
  family              = "postgres14"
  major_engine_version = "14"
  instance_class       = local.current_config.db_instance_class
  
  allocated_storage     = local.current_config.db_storage
  max_allocated_storage = local.current_config.db_max_storage
  
  # Network
  db_subnet_group_name   = module.vpc.database_subnet_group
  vpc_security_group_ids = [module.vpc.database_security_group_id]
  
  # Credentials
  manage_master_user_password = true
  
  tags = local.common_tags
}

Tool-Specific Usage

Terraform Configuration

# Provider configuration
terraform {
  required_version = ">= 1.0"
  
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
    }
  }
  
  backend "s3" {
    bucket = "my-terraform-state"
    key    = "infrastructure/terraform.tfstate"
    region = "us-west-2"
  }
}

provider "aws" {
  region = var.aws_region
  
  default_tags {
    tags = local.common_tags
  }
}

# Data sources
data "aws_ami" "amazon_linux" {
  most_recent = true
  owners      = ["amazon"]
  
  filter {
    name   = "name"
    values = ["amzn2-ami-hvm-*-x86_64-gp2"]
  }
}

data "aws_availability_zones" "available" {
  state = "available"
}

Nomad Job Specification

job "web-app" {
  datacenters = ["dc1", "dc2"]
  type        = "service"
  
  group "web" {
    count = 3
    
    network {
      port "http" {
        static = 8080
      }
    }
    
    task "server" {
      driver = "docker"
      
      config {
        image = "nginx:latest"
        ports = ["http"]
      }
      
      resources {
        cpu    = 500
        memory = 256
      }
      
      service {
        name = "web-app"
        port = "http"
        
        check {
          type     = "http"
          path     = "/health"
          interval = "10s"
          timeout  = "3s"
        }
      }
    }
  }
}

Consul Configuration

# Consul agent configuration
datacenter = "dc1"
data_dir   = "/opt/consul/data"
log_level  = "INFO"
server     = true

bind_addr = "0.0.0.0"
client_addr = "0.0.0.0"

bootstrap_expect = 3

retry_join = [
  "consul-1.example.com",
  "consul-2.example.com", 
  "consul-3.example.com"
]

ui_config {
  enabled = true
}

connect {
  enabled = true
}

acl = {
  enabled        = true
  default_policy = "deny"
  
  tokens {
    master = "your-master-token"
  }
}

Best Practices

Code Organization

# Use consistent formatting
variable "instance_type" {
  description = "EC2 instance type"
  type        = string
  default     = "t3.micro"
}

# Group related resources
# networking.tf
resource "aws_vpc" "main" { ... }
resource "aws_subnet" "public" { ... }
resource "aws_subnet" "private" { ... }

# compute.tf  
resource "aws_instance" "web" { ... }
resource "aws_autoscaling_group" "web" { ... }

# Use meaningful names
locals {
  web_security_group_rules = {
    http = {
      port        = 80
      protocol    = "tcp"
      cidr_blocks = ["0.0.0.0/0"]
    }
    https = {
      port        = 443
      protocol    = "tcp"
      cidr_blocks = ["0.0.0.0/0"]
    }
  }
}

Error Handling and Validation

# Input validation
variable "environment" {
  description = "Environment name"
  type        = string
  
  validation {
    condition     = contains(["dev", "staging", "prod"], var.environment)
    error_message = "Environment must be dev, staging, or prod."
  }
}

# Type constraints
variable "tags" {
  description = "Resource tags"
  type        = map(string)
  default     = {}
}

# Preconditions and postconditions
resource "aws_instance" "web" {
  ami           = data.aws_ami.amazon_linux.id
  instance_type = var.instance_type
  
  lifecycle {
    precondition {
      condition     = data.aws_ami.amazon_linux.architecture == "x86_64"
      error_message = "AMI must be x86_64 architecture."
    }
  }
}

Documentation

# Document variables thoroughly
variable "vpc_cidr" {
  description = <<-EOT
    CIDR block for the VPC. This should be a valid IPv4 CIDR block
    that doesn't conflict with existing networks. Common values:
    - 10.0.0.0/16 (65,536 IPs)
    - 172.16.0.0/12 (1,048,576 IPs) 
    - 192.168.0.0/16 (65,536 IPs)
  EOT
  type        = string
  
  validation {
    condition     = can(cidrhost(var.vpc_cidr, 0))
    error_message = "VPC CIDR must be a valid IPv4 CIDR block."
  }
}

# Use outputs for important values
output "vpc_id" {
  description = "ID of the VPC"
  value       = aws_vpc.main.id
}

output "public_subnet_ids" {
  description = "List of public subnet IDs"
  value       = aws_subnet.public[*].id
}

The HCL format provides a powerful and expressive configuration language that balances human readability with machine parsing capabilities, making it ideal for infrastructure as code and service configuration management.