Terraform basics: HCL, providers, resources and the workflow

Files and HCL syntax

Terraform reads every file ending in .tf in the current folder. Together they are one configuration. The language is HCL (HashiCorp Configuration Language). It has three building pieces.

• Blocks: a type, zero or more labels, and a body in curly braces, like resource "aws_s3_bucket" "logs" { ... }.
• Arguments: name = value lines inside a block, like bucket = "college-logs".
• Expressions: the values, such as strings, numbers, lists, maps, references to other things and function calls.

terraform {
  required_version = ">= 1.6"
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 6.0"   # any 6.x, never 7.0; check the registry for the current major version
    }
  }
}

provider "aws" {
  region = "ap-south-1"   # Mumbai
}

Providers

A provider is a plugin that knows how to talk to one API: AWS, Azure, Google Cloud, Kubernetes, GitHub, Cloudflare and many more. required_providers says which providers you need and which versions are allowed. The constraint "~> 6.0" means "6.0 or newer, but below 7.0", so a breaking major release is not picked up by surprise. terraform init downloads the providers.

Resources and references

A resource block declares one thing Terraform should create and manage. The first label is the resource type (from the provider), the second is your local name. Together they form the address, such as aws_s3_bucket.logs. You refer to an attribute of a resource with address.attribute, for example aws_s3_bucket.logs.id. Terraform uses these references to work out the order: a resource that refers to another is created after it.

resource "aws_s3_bucket" "logs" {
  bucket = "${var.project}-logs-${var.environment}"
  tags   = local.common_tags
}

resource "aws_s3_bucket_versioning" "logs" {
  bucket = aws_s3_bucket.logs.id   # reference: created after the bucket
  versioning_configuration {
    status = "Enabled"
  }
}

Data sources

A data block reads something that already exists, without managing it. For example, look up the newest Ubuntu image ID or an existing VPC created by another team. You refer to it as data.aws_ami.ubuntu.id.

Variables, outputs and locals

Input variables are the parameters of your configuration. Each has a type, an optional default, an optional description and optional validation rules. Mark secrets with sensitive = true so Terraform hides them in its output. Outputs print useful results after apply (and let other code read them). Locals are named values you compute once inside the configuration to avoid repeating yourself.

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

variable "db_password" {
  type      = string
  sensitive = true   # hidden in plan output, but still stored in state
}

locals {
  common_tags = { project = var.project, environment = var.environment, owner = "platform-team" }
}

output "logs_bucket_name" {
  value = aws_s3_bucket.logs.bucket
}

Many copies: count and for_each

count = 3 makes three copies addressed as aws_instance.web[0], [1] and [2]. for_each takes a map or a set of strings and makes one copy per key, addressed by key, like aws_s3_bucket.site["dev"]. Prefer for_each when items have names: if you remove the middle item of a count list, every later index shifts and Terraform wants to destroy and recreate them. With for_each only the removed key is affected.

resource "aws_s3_bucket" "site" {
  for_each = toset(["dev", "staging", "prod"])
  bucket   = "college-site-${each.key}"
}

The workflow

terraform init        # download providers, set up the backend (run once, and after changes to them)
terraform fmt         # format files in the standard style
terraform validate    # check syntax and internal consistency
terraform plan        # show what would change; changes nothing
terraform apply       # show the plan again, ask "yes", then make the changes
terraform destroy     # delete everything this configuration manages (careful!)

Reading a plan

The plan ends with a line such as "Plan: 2 to add, 1 to change, 1 to destroy." Look for "forces replacement" next to an argument: it means that change will delete and recreate the resource. For a database, that can mean data loss.

Common mistakes