Why HCL matters as Terraform's language - Why It Works This Way

Overview - Why HCL matters as Terraform's language

What is it?

HCL, or HashiCorp Configuration Language, is the language Terraform uses to describe cloud infrastructure. It is designed to be easy for humans to read and write, while also being structured enough for machines to understand. HCL lets you define resources like servers, networks, and databases in a clear, organized way. This makes managing cloud setups simpler and less error-prone.

Why it matters

Without HCL, writing infrastructure code would be much harder and more confusing. Imagine trying to explain your cloud setup in a complicated programming language or plain text. HCL solves this by giving a friendly, clear way to describe infrastructure that anyone on a team can understand and maintain. This reduces mistakes, speeds up cloud projects, and helps teams work together smoothly.

Where it fits

Before learning HCL, you should understand basic cloud concepts like servers and networks, and know what Terraform does. After mastering HCL, you can move on to advanced Terraform features like modules, state management, and automation. HCL is the foundation for writing Terraform configurations that control cloud resources.

Mental Model

Core Idea

HCL is a simple, human-friendly language designed to clearly describe cloud infrastructure so both people and machines can understand it easily.

Think of it like...

Think of HCL like a recipe card for baking a cake: it lists ingredients and steps in a clear, organized way that anyone can follow, whether they are a beginner or a professional baker.

Terraform Configuration (HCL)
┌─────────────────────────────┐
│ resource "type" "name" {  │
│   attribute = value          │
│   nested_block {            │
│     sub_attribute = value   │
│   }                        │
│ }                          │
└─────────────────────────────┘

This structure shows how resources and their settings are clearly laid out.

Build-Up - 6 Steps

1

Foundation

What is HCL and its purpose

Concept: Introducing HCL as a language made for describing infrastructure simply and clearly.

HCL stands for HashiCorp Configuration Language. It is a special language created to write down what cloud resources you want, like servers or databases. Unlike general programming languages, HCL focuses on clarity and ease of use. It looks like simple blocks with keys and values, making it easy to read and write.

Result

You can write a basic Terraform file that defines a resource in a way that is easy to understand.

Understanding that HCL is designed for humans first helps you appreciate why it looks different from typical programming languages.

2

Foundation

Basic HCL syntax and structure

Concept: Learning the simple building blocks of HCL: blocks, attributes, and values.

HCL uses blocks to group related settings. Each block has a type and a name, like resource "aws_instance" "web". Inside blocks, you set attributes with key = value pairs. Values can be strings, numbers, lists, or maps. Blocks can also nest inside each other for more detail.

Result

You can write a small configuration with a resource block and some attributes correctly formatted.

Knowing the basic syntax lets you start writing and reading Terraform files confidently.

3

Intermediate

Why HCL is better than JSON or YAML

🤔Before reading on: do you think JSON or YAML would be easier or harder than HCL for Terraform configs? Commit to your answer.

Concept: Understanding the advantages of HCL over other common configuration languages.

Terraform can use JSON, but HCL is preferred because it is more readable and concise. JSON requires many quotes and commas, making it cluttered. YAML can be ambiguous and sensitive to spaces. HCL balances strict structure with readability, making it easier to spot errors and understand intent.

Result

You realize that HCL reduces mistakes and improves collaboration compared to JSON or YAML.

Knowing why HCL was chosen helps you trust and use it effectively instead of trying to force other formats.

4

Intermediate

HCL's support for expressions and variables

🤔Before reading on: do you think HCL can do calculations and reuse values, or is it just static text? Commit to your answer.

Concept: Introducing how HCL allows dynamic values using expressions and variables.

HCL lets you write expressions like adding numbers or referencing variables. Variables let you reuse values and customize configurations without repeating yourself. For example, you can define a variable for a server size and use it in multiple places. This makes configurations flexible and easier to maintain.

Result

You can write Terraform files that adapt to different inputs and environments.

Understanding expressions and variables unlocks the power of reusable and dynamic infrastructure code.

5

Advanced

How HCL integrates with Terraform's workflow

🤔Before reading on: do you think HCL files are just static descriptions, or do they interact with Terraform's state and plans? Commit to your answer.

Concept: Explaining how HCL files are the input that Terraform reads to create plans and apply changes.

Terraform reads HCL files to understand what resources you want. It compares this to the current cloud state and creates a plan to reach the desired setup. HCL's clear structure helps Terraform parse and validate configurations quickly. Changes in HCL files trigger updates in cloud resources.

Result

You see how writing good HCL directly affects how Terraform manages your infrastructure.

Knowing HCL's role in the Terraform lifecycle helps you write better, error-free configurations.

6

Expert

HCL's design trade-offs and extensibility

🤔Before reading on: do you think HCL is a full programming language or something simpler? Commit to your answer.

Concept: Understanding why HCL is not a full programming language and how this affects its use and extension.

HCL is designed to be declarative and simple, not a full programming language. This limits complexity but improves safety and readability. It supports functions and expressions but avoids loops or complex logic. Extensions come via Terraform providers and modules, keeping HCL focused on describing infrastructure clearly.

Result

You appreciate the balance HCL strikes between power and simplicity, and how it fits into Terraform's ecosystem.

Recognizing HCL's deliberate limits helps avoid overcomplicating configurations and guides you to use modules and providers for advanced needs.

Under the Hood

Terraform uses a parser to read HCL files and convert them into an internal data structure representing resources and their attributes. This structure is then used to compare desired state with actual cloud state. HCL's syntax is designed to be unambiguous and easy to parse, which speeds up validation and error detection. The language supports interpolation and expressions that Terraform evaluates during planning and applying.

Why designed this way?

HCL was created to solve the problem of writing infrastructure code that is both human-friendly and machine-readable. Early tools used JSON or XML, which were hard to read and write. HCL's design focuses on clarity, simplicity, and safety, avoiding the complexity of full programming languages to reduce bugs and misunderstandings. This design encourages best practices and collaboration.

┌───────────────┐       ┌───────────────┐       ┌───────────────┐
│  HCL File     │──────▶│  Terraform    │──────▶│  Cloud APIs   │
│ (human input) │       │  Parser &     │       │ (create/update│
│               │       │  Interpreter  │       │  resources)   │
└───────────────┘       └───────────────┘       └───────────────┘

HCL files feed Terraform, which interprets and acts on cloud providers.

Myth Busters - 3 Common Misconceptions

Quick: Is HCL a full programming language like Python or Java? Commit yes or no.

Common Belief: HCL is just another programming language with loops and complex logic.

Reality: HCL is a declarative configuration language designed for simplicity and clarity, without full programming features like loops or conditionals.

Why it matters: Expecting programming features leads to trying to write complex logic in HCL, causing confusion and errors.

Quick: Can you write Terraform configurations equally well in JSON as in HCL? Commit yes or no.

Common Belief: JSON is just as good as HCL for Terraform configurations.

Reality: While Terraform supports JSON, HCL is much easier to read, write, and maintain, making it the preferred choice.

Why it matters: Using JSON can make configurations harder to understand and maintain, increasing the chance of mistakes.

Quick: Does HCL automatically handle all cloud provider details for you? Commit yes or no.

Common Belief: HCL abstracts away all cloud provider complexities automatically.

Reality: HCL describes what you want, but you still need to understand cloud resources and their settings to write effective configurations.

Why it matters: Assuming HCL hides all complexity can lead to misconfigured infrastructure and unexpected behavior.

Expert Zone

1

HCL's design intentionally limits complexity to encourage declarative infrastructure, pushing complex logic into modules or external tools.

2

Interpolation and expressions in HCL are evaluated during Terraform's plan phase, not at runtime, affecting how dynamic values behave.

3

HCL's syntax allows comments and formatting that improve collaboration but must be used carefully to avoid parsing errors.

When NOT to use

HCL is not suitable when you need full programming capabilities like loops or complex conditionals; in such cases, use external scripting languages or tools to generate Terraform configurations. Also, for very simple or automated tasks, direct cloud provider APIs or other IaC tools might be better.

Production Patterns

In production, teams use HCL with modules to reuse and share infrastructure code, variables for environment customization, and workspaces for managing multiple deployments. They also integrate HCL files with CI/CD pipelines for automated testing and deployment.

Connections

Declarative Programming

HCL is a declarative language, similar in concept to declarative programming paradigms.

Understanding declarative programming helps grasp why HCL focuses on describing 'what' rather than 'how', improving clarity and reducing errors.

Recipe Writing

Both HCL and recipes provide step-by-step instructions in a clear, structured format.

Seeing HCL as a recipe helps understand its goal: to communicate instructions clearly so anyone can follow and reproduce the result.

Human-Computer Interaction (HCI)

HCL design balances human readability with machine parsability, a core concern in HCI.

Knowing HCI principles explains why HCL avoids overly complex syntax and prioritizes clarity, making it easier for teams to collaborate.

Common Pitfalls

#1 Writing complex logic directly in HCL expecting it to behave like a programming language.

Wrong approach:

resource "aws_instance" "example" {
count = for i in range(3) : i
# This is invalid syntax in HCL
}

Correct approach:

variable "instance_count" {
type = number
default = 3
}

resource "aws_instance" "example" {
count = var.instance_count
# Use count with a variable, no loops
}

Root cause:

Misunderstanding that HCL is declarative and does not support loops or complex programming constructs.

#2 Using JSON format for Terraform configurations to save time.

Wrong approach:

{
"resource": {
"aws_instance": {
"example": {
"ami": "ami-123456",
"instance_type": "t2.micro"
}
}
}
}

Correct approach:

resource "aws_instance" "example" {
ami = "ami-123456"
instance_type = "t2.micro"
}

Root cause:

Not realizing that JSON is harder to read and maintain compared to HCL, leading to more errors.

#3 Assuming HCL automatically manages all cloud provider details without user input.

Wrong approach:

resource "aws_instance" "example" {
# Missing required attributes like ami or instance_type
}

Correct approach:

resource "aws_instance" "example" {
ami = "ami-123456"
instance_type = "t2.micro"
}

Root cause:

Believing HCL abstracts all cloud details, ignoring the need to specify required resource attributes.

Key Takeaways

HCL is a simple, human-friendly language designed specifically to describe cloud infrastructure clearly and safely.

Its declarative nature means you describe what you want, not how to do it, making configurations easier to read and maintain.

HCL balances readability and machine parsing better than JSON or YAML, reducing errors and improving collaboration.

While HCL supports expressions and variables, it is not a full programming language, so complex logic belongs outside it.

Understanding HCL's role in Terraform's workflow helps you write effective infrastructure code that Terraform can plan and apply reliably.