Learn the Basics of HashiCorp Configuration Language HCL

Welcome to this concise guide to HashiCorp Configuration Language (HCL) — the primary language used to write Terraform configurations. This article explains what HCL is, why Terraform uses it, and how to read, write, and organize HCL files so your infrastructure-as-code (IaC) is clear, consistent, and maintainable. HCL is a domain-specific, declarative configuration language designed to describe infrastructure in a human-friendly way. It strikes a balance between simplicity and expressiveness so both new users and experienced operators can declare infrastructure intent that Terraform can act on.

Declarative nature

Terraform (and HCL) is declarative: you describe the desired state of your infrastructure, not the imperative steps to reach it. Think of it like ordering at a restaurant — you state the final dish you want, and the chef handles the preparation. HCL’s readability makes configurations easier to understand, review, and maintain, improving collaboration across teams.

HCL structure overview

HCL code is composed of blocks. Blocks group related configuration and follow a predictable pattern:

A block type (keyword) — e.g., resource, data, provider.
Zero or more labels — e.g., resource type and name: "aws_vpc" "vpc".
A body in curly braces { ... } containing attributes (arguments) or nested blocks.

HCL supports comments:

Single-line: # comment or // comment
Multi-line: /* multi-line comment */

Generic HCL block example:

# single-line comment
block_type "block_label" "block_label" {
  first_argument  = expression_or_value
  second_argument = expression_or_value
  third           = expression_or_value
}

attribute_abc = "value_1"
attribute_2   = "value_2"

Example (main.tf)

Terraform files use the .tf extension (for example, main.tf). The example below shows data blocks (read-only lookups) and a resource block (declares infrastructure to create/manage).

# Retrieve the list of AZs in the current AWS region
data "aws_availability_zones" "available" {}

# Retrieve the current AWS region name
data "aws_region" "current" {}

# Define the VPC
resource "aws_vpc" "vpc" {
  cidr_block = var.vpc_cidr

  tags = {
    Name        = var.vpc_name
    Environment = "demo_environment"
    Terraform   = "true"
  }
}

Notes on the example:

data blocks perform lookups of existing information (no additional arguments required in this example).
The resource block defines an AWS VPC with the cidr_block attribute and a tags map.
Inline comments (prefixed with #) document intent — recommended but optional.

Block anatomy (detailed)

Breakdown of the resource block:

resource "aws_vpc" "vpc" {
  cidr_block = var.vpc_cidr

  tags = {
    Name        = var.vpc_name
    Environment = "demo_environment"
    Terraform   = "true"
  }
}

resource — block type: declares infrastructure managed by Terraform.
"aws_vpc" — resource type: specific provider resource.
"vpc" — resource name: a local identifier used to reference this resource in the configuration (e.g., aws_vpc.vpc).
{ ... } — block body that contains attributes and nested blocks.
Inside the block are attributes (arguments) such as cidr_block and the tags map.

To reference this resource elsewhere in your configuration, use aws_vpc.vpc. If you create multiple VPCs, give each resource a unique name (for example, aws_vpc.prod and aws_vpc.test).

Style and conventions

Consistent formatting and naming make HCL easier to read and collaborate on. Below are common conventions used across the Terraform ecosystem:

Topic	Recommendation	Example
Comments	Use `#` or `//` for single-line and `/* ... */` for multi-line	`# This documents intent`
Naming	Use `snake_case` for resource/variable names	`vpc_name`, `subnet_id`
Indentation	Use two spaces per level; avoid tabs	(2-space indentation)
Equals alignment	Align `=` vertically within related groups (local to the block)	`first_argument = "value"`
File extension	Place configurations in `.tf` files	`main.tf`

Example alignment style inside a block:

first_argument  = "value"
second_argument = "another value"
third           = "short"

Use blank lines to separate logical groups of arguments within a block to improve readability. Modern editors like Visual Studio Code and the HashiCorp Terraform extension can auto-format and lint HCL to these conventions.

Use terraform fmt or your editor extension to automatically format HCL to standard style.

Best practices and tips

Keep variables and outputs well-documented with description fields.
Group related resources in modules for reuse and separation of concerns.
Avoid committing sensitive secrets directly — use secure variable management or secret backends.
Prefer small, focused modules and clear naming to make state management and drift detection easier.
Use terraform validate and terraform plan to catch errors before applying changes.

Summary

HCL is a readable, declarative language tailored for Terraform and infrastructure-as-code:

Describe the desired state; Terraform determines the steps.
Organize configurations into blocks with types, labels, and bodies.
Follow conventions: comments, snake_case naming, two-space indentation, and aligned equals for clarity.
Use terraform fmt, terraform validate, and editor tooling to maintain consistency.

By following these patterns and conventions, you’ll be able to write maintainable, collaborative Terraform configurations for real-world infrastructure projects.

Links and references

HashiCorp Terraform docs: https://developer.hashicorp.com/terraform
HCL specification: https://github.com/hashicorp/hcl
Visual Studio Code: https://code.visualstudio.com/
HashiCorp Terraform extension for VS Code: https://marketplace.visualstudio.com/items?itemName=HashiCorp.terraform

Course Introduction

Preparing Your Environment

Terraform Foundations

The Core Terraform Workflow

Terraform CLI

Terraform File Structure and Organization

Terraform Configuration - Fundamentals

Understading and Managing Terraform State

Marking Code Reusable

Refactoring Terraform State

Terraform Modules

Managing Resource Behavior and Dependencies

Securing Terraform Configurations

Terraform Troubleshooting

HCP Terraform

Learn the Basics of HashiCorp Configuration Language HCL

Declarative nature

HCL structure overview

Example (main.tf)

Block anatomy (detailed)

Style and conventions

Best practices and tips

Summary

Links and references

Watch Video

​Declarative nature

​HCL structure overview

​Example (main.tf)

​Block anatomy (detailed)

​Style and conventions

​Best practices and tips

​Summary

​Links and references

Watch Video

Declarative nature

HCL structure overview

Example (main.tf)

Block anatomy (detailed)

Style and conventions

Best practices and tips

Summary

Links and references