Skip to content
Tutorials Center
My learning

Topics

Lesson 54 of 70 ยท Infrastructure as code

Terraform on AWS

Learn Terraform on AWS: providers, resources, state, plan and apply, modules and remote state in S3, compared with CloudFormation and CDK, with runnable plan and state emulators.

CloudFormation and the CDK are AWS's own answers to infrastructure as code. Terraform is the best-known alternative. It is an open-source tool (originally from HashiCorp; the OpenTofu fork is command-compatible for everything in this lesson) that reads configuration files written in a language called HCL and makes real infrastructure match them. It is not tied to AWS. The same workflow manages AWS, Azure, Google Cloud, GitHub, Cloudflare and hundreds of other services, which is the main reason teams pick it.

The idea is simple: you describe the desired state, Terraform compares it with what it believes exists (its state), shows you a plan, and after you approve it, calls the AWS APIs to close the gap. This lesson covers providers, resources, state, the plan and apply cycle, modules and remote state in S3, and ends with an honest comparison with CloudFormation and CDK.

Terraform needs real credentials and a real account, so all HCL and CLI commands here are read-only. The runnable examples are Python stand-ins: a plan-diff engine that decides what to create, change, replace or destroy, and a remote state store with locking. They show the logic, not the real implementation, and each section says what is simplified.

Providers and resources

Terraform itself knows nothing about AWS. A provider is a plugin that does. The aws provider turns resource blocks into API calls, and terraform init downloads it.

HCL
terraform {
  required_version = ">= 1.9"

  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 6.0"
    }
  }
}

provider "aws" {
  region = "eu-west-1"

  default_tags {
    tags = {
      Project = "uploads"
    }
  }
}

resource "aws_s3_bucket" "uploads" {
  bucket = "example-uploads-123456789012"
}

resource "aws_s3_bucket_versioning" "uploads" {
  bucket = aws_s3_bucket.uploads.id

  versioning_configuration {
    status = "Enabled"
  }
}

A resource block has a type (aws_s3_bucket), a local name (uploads) and arguments. Together, aws_s3_bucket.uploads is the resource's address, its identity inside Terraform. The line bucket = aws_s3_bucket.uploads.id is a reference to another resource's attribute. Terraform reads references to build a dependency graph, so it creates the bucket before the versioning setting, with no depends_on needed.

The provider uses the same credential chain as the CLI and SDKs (see Console, CLI and SDKs): environment variables, a profile, or an SSO session. Never write access keys into .tf files. Using a role is better still; see IAM users, groups and roles.

Two more block types make configurations reusable.

HCL
variable "environment" {
  type    = string
  default = "dev"

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

locals {
  bucket_name = "example-uploads-${var.environment}"
}

output "bucket_arn" {
  value = aws_s3_bucket.uploads.arn
}

data "aws_caller_identity" "current" {}

variable is an input, locals holds computed names, output publishes a value, and data reads something that already exists (here, the current account) instead of creating it.

The workflow: init, plan, apply

Terminal
terraform init      # download providers and modules, set up the backend
terraform fmt       # format the files
terraform validate  # check syntax and references
terraform plan -out=tfplan
terraform apply tfplan
terraform destroy

plan is the heart of Terraform. It refreshes what it knows about real resources, compares that with your configuration and prints each action:

TEXT
  # aws_s3_bucket.uploads will be created
  + resource "aws_s3_bucket" "uploads" { ... }

Plan: 2 to add, 0 to change, 0 to destroy.

The symbols are worth memorizing: + create, - destroy, ~ update in place, and -/+ destroy and re-create (a replacement). Some arguments cannot be changed on a live resource. The name of an S3 bucket is one: changing it means a new bucket. Terraform reads that from the provider's schema and plans a replacement. Always read the line forces replacement in a plan before you apply, because replacing a database can lose data.

flowchart LR
    A["*.tf files<br/>(desired state)"] --> P["terraform plan"]
    S["State file<br/>(what Terraform recorded)"] --> P
    R["Real AWS resources<br/>(refresh)"] --> P
    P --> D["Plan: create, update,<br/>replace, destroy"]
    D --> AP["terraform apply"]
    AP --> R
    AP --> S

Plan compares three things: your code, the saved state and the real world. Apply changes the real world and then updates the state.

A plan-diff stand-in

The next example is a toy plan engine. A resource is a dictionary of arguments, and a small table lists which arguments force replacement. It compares desired configuration with the recorded state and prints a plan in Terraform's style. Real Terraform asks the provider schema for this information and also compares refreshed real attributes, handles unknown values and computes dependency order for you.

Python Plan: create, update, replace, destroy

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

You should see the new queue created, the bucket updated in place, the instance replaced (its ami is a forcing argument while instance_type alone would not be) and the old logs bucket destroyed. The summary counts a replacement as one add plus one destroy, as Terraform does.

State

Terraform must remember which real resource belongs to which block. That memory is the state, by default a JSON file called terraform.tfstate. It maps each address to a real ID (a bucket name, an instance ID, an ARN) plus the attributes Terraform last saw.

State matters for three reasons.

  • Mapping. Without it, Terraform could not tell "my bucket" from the thousand others in the account.
  • Performance. Terraform can read attributes from state instead of describing every resource each time.
  • Dependencies and metadata. It stores the order in which resources were created.

State often contains secrets in plain text (a generated database password, for example), so treat it like a credential. Never commit it to Git. And never edit it by hand: use terraform state list, terraform state mv (rename an address without replacing the resource) and terraform import (adopt an existing resource into state) instead. Modern Terraform also has import and moved blocks that record those operations in code, where they can be reviewed.

HCL
moved {
  from = aws_s3_bucket.logs
  to   = aws_s3_bucket.access_logs
}

Without the moved block, renaming a resource looks like "destroy the old one, create a new one". CloudFormation has the same trap with logical IDs, as the CDK lesson shows.

Remote state in S3

A local state file works for one person on one laptop. A team needs a shared state that is locked while someone applies, otherwise two simultaneous applies can corrupt it. The standard AWS setup is an S3 bucket, with versioning and encryption turned on (see S3 storage classes and lifecycle and S3 security).

HCL
terraform {
  backend "s3" {
    bucket       = "acme-terraform-state-123456789012"
    key          = "uploads/prod/terraform.tfstate"
    region       = "eu-west-1"
    encrypt      = true
    use_lockfile = true
  }
}

use_lockfile = true makes Terraform take its lock by writing a small .tflock object next to the state with an S3 conditional write, so only one writer succeeds. Older guides use a DynamoDB table for locking (dynamodb_table = "..."), which still works but is deprecated. The state bucket is the one resource you create outside the configuration it stores: make it by hand or with a tiny separate configuration, turn on versioning so you can roll back a bad state, and block public access.

Backend blocks cannot use variables, so teams pass settings at init time with terraform init -backend-config=prod.hcl. A common layout is one state file per environment and component (uploads/prod, uploads/dev), so a mistake in one cannot take down the others. Another configuration can read published outputs from a state with a terraform_remote_state data source, though many teams prefer to look up values with ordinary data blocks to avoid coupling.

A remote state store with locking

This stand-in keeps a "bucket" of state objects. Each apply must first take a lock, write a new state with a higher serial, and release the lock. A second writer arriving during the first apply is refused. Real S3 locking uses conditional writes and prints a lock ID and holder, and the state also carries a lineage so Terraform can detect that you pointed at the wrong file.

Python Two applies compete for the state lock

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Carol's first attempt is refused, and she succeeds once Bob's lock is released. In real life Terraform waits and prints the lock details, or you pass -lock-timeout=5m to retry for a while. If a crashed run leaves a stale lock, terraform force-unlock <ID> removes it, but only after you are sure nobody is applying.

Modules

A module is a folder of .tf files that you call with its own inputs and outputs. Every configuration is itself a module (the root module), and you can call others to avoid copy-pasting the same pattern.

HCL
module "uploads" {
  source = "./modules/private-bucket"

  name        = "acme-uploads"
  versioning  = true
  environment = var.environment
}

output "uploads_arn" {
  value = module.uploads.arn
}

Inside modules/private-bucket, the files declare variable inputs, create the bucket, public access block and encryption settings, and expose output "arn". Resources inside a module get addresses prefixed with the module path, for example module.uploads.aws_s3_bucket.this. Modules can come from a local path, a Git repository or the public Terraform Registry (source = "terraform-aws-modules/vpc/aws" with a pinned version). Pin versions and read a registry module's source before you trust it with production.

Two habits keep modules healthy: expose only the inputs a caller needs, and avoid giant "do everything" modules. Use for_each over a map to create several resources from one block, so each gets a stable key-based address instead of a fragile index.

HCL
resource "aws_sqs_queue" "queue" {
  for_each = toset(["emails", "images", "reports"])
  name     = "acme-${each.key}"
}

Terraform, CloudFormation and CDK

All three describe AWS infrastructure and all three compute a plan before changing it. They differ in where the state lives and how far they reach.

CloudFormation CDK Terraform
Language YAML or JSON TypeScript, Python, Java, C#, Go HCL
State Kept by AWS in the stack Same as CloudFormation Your file, usually in S3
Preview Change set cdk diff terraform plan
Rollback on failure Automatic Automatic None: partial progress stays
Beyond AWS No (custom resources only) No Yes, thousands of providers
New AWS features Often day one, sometimes later After CloudFormation Provider release needed
Cost Free Free Free CLI (paid HCP Terraform optional)

The biggest practical difference is state. CloudFormation owns it for you, so you cannot lose it or corrupt it, but you also cannot easily inspect or repair it. Terraform hands you the state file, which gives flexibility and an extra thing to protect. Terraform also does not roll back: if the third of five resources fails, the first two stay created and the next apply continues from there.

A reasonable rule: if you only use AWS and want the least to operate, CloudFormation or CDK fit well. If your team already knows Terraform, or you also manage non-AWS services in the same workflow, Terraform is a strong choice. Mixing tools inside one stack of resources is a recipe for confusion, so give each resource exactly one owner.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does terraform plan do?

    Plan is a preview. It changes nothing; apply (ideally with a saved plan) performs the actions.
  2. 2. A plan shows "-/+" next to a database with "forces replacement" on one argument. What will happen on apply?

    Some arguments cannot be changed on a live resource. Terraform plans a replacement, which can lose data unless you have a backup or change the design.
  3. 3. Why does a team keep Terraform state in an S3 bucket with locking instead of on each laptop?

    Shared state keeps the team consistent, and the lock prevents two simultaneous applies from corrupting it. Turn on bucket versioning too, so you can recover an earlier state.
  4. 4. What does a moved block do?

    Without it, a renamed resource looks like one removed and one new resource. The moved block records the rename in code, where reviewers can see it.
  5. 5. Which statement about Terraform and CloudFormation is correct?

    Terraform's provider model reaches far beyond AWS, but state is your responsibility. CloudFormation owns state and rolls back automatically, while Terraform leaves partial progress in place.

Summary

  • Terraform reads HCL files and, through providers such as hashicorp/aws, makes real infrastructure match the described desired state.
  • The workflow is init, plan, apply; read every forces replacement and -/+ line before approving.
  • State maps resource addresses to real IDs and may contain secrets. Keep it out of Git, never edit it by hand, and use state mv, import and moved blocks to change it safely.
  • Teams store state remotely in S3 with versioning, encryption and locking (use_lockfile = true).
  • Modules package reusable patterns; pin their versions and use for_each for stable addresses.
  • Compared with CloudFormation and CDK, Terraform spans many providers but leaves state and partial failures to you.

Next: Well-Architected Framework