Terraform HCL Syntax Configuration Beginner

Understanding Terraform HCL Syntax: Blocks, Parameters, and Arguments

Published on: November 3, 2023 | Author: DevOps Engineering Team

Mastering Terraform HCL Syntax

Welcome to Part 2 of our Terraform Mastery Series! In this guide, we'll dive deep into Terraform's HashiCorp Configuration Language (HCL) syntax. Understanding blocks, parameters, and arguments is fundamental to writing effective, maintainable Terraform configurations.

What You'll Learn

• What is HCL?
• Basic HCL Syntax Rules
• Understanding Blocks
• Parameters vs Arguments
• HCL Expressions
• Common Syntax Patterns
• HCL Best Practices
• Advanced HCL Features

What is HCL?

HashiCorp Configuration Language (HCL) is a declarative language designed for building infrastructure configurations. It's human-readable, machine-friendly, and specifically crafted for DevOps workflows.

HCL Design Goals

• Human Readable: Easy for humans to write and understand
• Machine Friendly: Easy for machines to parse and validate
• Composable: Modular and reusable components
• Toolable: Great editor support and tooling

HCL vs JSON

• HCL is more concise than JSON
• Supports comments and documentation
• Better readability for complex structures
• Native support for expressions and functions

HCL and JSON Compatibility

HCL is fully compatible with JSON. You can use JSON syntax within HCL files, and Terraform can parse both formats. However, HCL is preferred for its readability and features.

Basic HCL Syntax Rules

Before diving into complex concepts, let's cover the fundamental syntax rules of HCL.

1

Key-Value Pairs

The most basic element in HCL is the key-value pair:

key = "value"
number = 42
boolean = true

2

Comments

HCL supports single-line and multi-line comments:

# Single line comment
// Also single line comment
/* 
Multi-line comment
Spanning multiple lines
*/

3

Indentation and Formatting

HCL is not whitespace-sensitive, but consistent formatting improves readability:

# Good formatting
resource "aws_instance" "web" {
  ami           = "ami-123456"
  instance_type = "t3.micro"
  
  tags = {
    Name = "Web Server"
  }
}

Understanding Blocks

Blocks are the primary structural element in HCL. They define resources, data sources, providers, and other components.

Block Type

Labels

resource "aws_instance" "web_server" {

ami = "ami-0c02fb55956c7d316"

Argument

instance_type = "t3.micro"

}

Resource Blocks

# Resource Block Structure
resource "PROVIDER_TYPE" "RESOURCE_NAME" {
  # Configuration arguments
  ARGUMENT_NAME = ARGUMENT_VALUE
}

# Concrete Example
resource "aws_instance" "web_server" {
  ami           = "ami-0c02fb55956c7d316"
  instance_type = "t3.micro"
  
  tags = {
    Name        = "WebServer"
    Environment = "production"
  }
}

Block Type: resource
Labels: "aws_instance" (resource type) and "web_server" (local name)
Body: Contains configuration arguments for the resource

Provider Blocks

# Provider Configuration
provider "aws" {
  region = "us-east-1"
  profile = "production"
}

# Multiple Provider Configurations
provider "aws" {
  region = "us-east-1"
  alias = "primary"
}

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

Provider blocks configure how Terraform interacts with cloud providers. The alias parameter allows multiple configurations for the same provider.

Variable and Output Blocks

# Variable Block
variable "instance_type" {
  description = "The type of instance to create"
  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."
  }
}

# Output Block
output "instance_ip" {
  description = "The public IP of the instance"
  value       = aws_instance.web_server.public_ip
  sensitive   = false
}

Variable blocks define input parameters, while output blocks expose values for other configurations or users.

Common Block Types

Block Type	Purpose	Example
terraform	Terraform configuration	terraform { required_version = ">= 1.0" }
provider	Configure cloud providers	provider "aws" { region = "us-east-1" }
resource	Create infrastructure resources	resource "aws_instance" "web" { ... }
data	Fetch existing data	data "aws_ami" "ubuntu" { ... }
variable	Define input variables	variable "instance_count" { type = number }
output	Export values	output "ip" { value = aws_instance.web.private_ip }
module	Call reusable modules	module "vpc" { source = "./modules/vpc" }
locals	Define local values	locals { common_tags = { ... } }

Parameters vs Arguments

Understanding the difference between parameters and arguments is crucial for writing correct HCL configurations.

Parameters

• Define what can be configured
• Specified in block definitions
• Define the schema for a resource type
• Fixed by the provider

# These are PARAMETERS defined by aws_instance resource type
ami
instance_type 
vpc_security_group_ids
tags

Arguments

• Provide values for parameters
• Set in your configuration
• Specific to your use case
• Your actual configuration values

# These are ARGUMENTS you provide
ami = "ami-0c02fb55956c7d316"
instance_type = "t3.micro"
tags = { Name = "WebServer" }

Key Difference

Parameters are the "slots" available for configuration (defined by resource types). Arguments are the actual values you put in those slots (defined in your code).

Argument Types

HCL supports various argument types for different use cases:

Primitive Types

# String
name = "web-server"

# Number
count = 3
port = 8080

# Boolean
encrypted = true
public = false

# Any (dynamic typing)
settings = "can be any type"

Collection Types

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

# Set (unique values)
security_groups = toset(["sg-123456", "sg-789012"])

# Map (key-value pairs)
tags = {
  Name        = "Production"
  Environment = "prod"
  Owner       = "DevOps"
}

# Object (structured data)
database_config = {
  engine   = "mysql"
  version  = "8.0"
  port     = 3306
  backup   = true
}

Complex Nested Structures

# Nested blocks
ingress {
  description = "HTTP"
  from_port   = 80
  to_port     = 80
  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"]
}

# List of objects
server = [
  {
    name     = "web-1"
    type     = "t3.micro"
    az       = "us-east-1a"
  },
  {
    name     = "web-2"
    type     = "t3.small"
    az       = "us-east-1b"
  }
]

HCL Expressions

Expressions allow you to compute values dynamically. They're a powerful feature that makes HCL configurations flexible and reusable.

References

Reference values from other resources, data sources, or variables:

subnet_id = aws_subnet.public.id
ami = data.aws_ami.ubuntu.id
type = var.instance_type

Functions

Use built-in functions for transformations and calculations:

name = lower(var.environment_name)
cidr = cidrsubnet(var.vpc_cidr, 8, 1)
timestamp = timestamp()

Conditionals

Make decisions based on conditions:

count = var.create_resource ? 1 : 0
type = var.environment == "prod" ? "m5.large" : "t3.micro"

String Interpolation

Combine strings with expressions:

name = "${var.project}-${var.environment}-instance"
description = "Instance created on ${timestamp()}"

Interactive Expression Demo

Try these expressions to see how they work:

Select an expression type to see examples...

Common Syntax Patterns

Here are some common HCL patterns you'll encounter frequently:

Dynamic Blocks

# Create multiple similar configurations dynamically
resource "aws_security_group" "web" {
  name = "web-sg"
  
  dynamic "ingress" {
    for_each = var.ingress_rules
    content {
      description = ingress.value.description
      from_port   = ingress.value.port
      to_port     = ingress.value.port
      protocol    = "tcp"
      cidr_blocks = ingress.value.allowed_cidrs
    }
  }
}

# Variable definition for the above
variable "ingress_rules" {
  type = map(object({
    description   = string
    port         = number
    allowed_cidrs = list(string)
  }))
  default = {
    "http" = {
      description   = "HTTP access"
      port         = 80
      allowed_cidrs = ["0.0.0.0/0"]
    }
    "https" = {
      description   = "HTTPS access"
      port         = 443
      allowed_cidrs = ["0.0.0.0/0"]
    }
  }
}

Count and For Each

# Using count for multiple similar resources
resource "aws_instance" "web" {
  count = 3
  
  ami           = "ami-0c02fb55956c7d316"
  instance_type = "t3.micro"
  
  tags = {
    Name = "web-server-${count.index + 1}"
  }
}

# Using for_each for distinct resources
resource "aws_instance" "app" {
  for_each = toset(["api", "worker", "cache"])
  
  ami           = "ami-0c02fb55956c7d316"
  instance_type = "t3.micro"
  
  tags = {
    Name = "${each.key}-server"
    Role = each.value
  }
}

Local Values and Complex Expressions

# Define local values for reuse
locals {
  common_tags = {
    Project     = var.project_name
    Environment = var.environment
    ManagedBy   = "Terraform"
  }
  
  instance_name = "${var.project_name}-${var.environment}"
  
  # Complex transformation
  subnet_configs = {
    for i, az in var.availability_zones : az => {
      cidr_block = cidrsubnet(var.vpc_cidr, 8, i)
      az         = az
    }
  }
}

# Use locals in resources
resource "aws_instance" "web" {
  ami           = var.ami_id
  instance_type = var.instance_type
  
  tags = merge(local.common_tags, {
    Name = local.instance_name
  })
}

HCL Best Practices

Code Organization

• Use consistent indentation (2 spaces)
• Group related resources together
• Use empty lines to separate logical sections
• Keep line length reasonable (max 80-120 chars)

Naming Conventions

• Use snake_case for all identifiers
• Choose descriptive names for resources
• Be consistent with naming patterns
• Avoid abbreviations unless well-known

Maintainability

• Use variables for configurable values
• Define locals for complex expressions
• Add meaningful descriptions
• Use consistent formatting with terraform fmt

Validation and Safety

• Validate variable inputs
• Use sensitive = true for sensitive outputs
• Add lifecycle blocks for resource management
• Test configurations with terraform validate

Advanced HCL Features

As you become more comfortable with HCL, you can leverage these advanced features:

Terraform Functions

# String functions
lowercase_name = lower(var.name)
formatted = format("Hello, %s!", var.username)

# Collection functions
unique_zones = distinct(var.availability_zones)
sorted_list = sort(var.instance_types)

Complex Type Constraints

variable "network_config" {
  type = object({
    vpc_cidr    = string
    subnets     = map(object({
      cidr = string
      az   = string
    }))
    enable_nat  = bool
  })
}

Key Takeaways

• Blocks are the main structural element in HCL configurations
• Parameters define what can be configured, arguments provide actual values
• HCL supports primitive types, collections, and complex nested structures
• Expressions make configurations dynamic and reusable
• Use terraform fmt to maintain consistent formatting
• Follow naming conventions and organization best practices

In our next tutorial, we'll explore Terraform Variables and Outputs in depth, where you'll learn how to make your configurations more flexible and reusable.

---

← Previous: How to Install Terraform and Create Your First Resource

This is Part 2 of The Ultimate Terraform Mastery Series.

Next: Mastering Terraform Variables and Outputs →