Lesson 08 — Terraform Basics + Remote State

Replace the cloud console with code. Then teach the code to share itself.

Recap — What L07 left unfinished

“If you can’t describe it as code, you can’t repeat it reliably.”

What Terraform actually is

• A CLI that reads .tf files and talks to cloud APIs.
• Declarative: you say what you want; Terraform figures out how to get there.
• Reconciler: computes the diff between desired (.tf) and actual (real cloud), then applies the minimum delta — same shape as docker compose up -d.
• State-aware: remembers every resource it created in a JSON file (terraform.tfstate). That state must be shared between teammates — hence “remote state.”
• Provider-agnostic: same syntax targets AWS, GCP, Azure, Cloudflare, GitHub, Datadog…

The four files you write

main.tf       # resources: the VM, security group, key pair, EIP
variables.tf  # input knobs: region, instance_type, ssh_key_name
outputs.tf    # what to print after apply: public IP, ssh command
versions.tf   # pin Terraform + provider versions

That’s the whole project for a single VM — roughly 80 lines of HCL. Add user_data.sh (the first-boot script) and terraform/backend/ for the remote-state bootstrap and you have the complete Module 3 Terraform tree.

The provider block (versions.tf)

terraform {
  required_version = ">= 1.6.0"
  required_providers {
    aws = { source = "hashicorp/aws", version = "~> 5.0" }
  }
}

provider "aws" {
  region = var.region
}

• Declares “we use AWS’s API”.
• terraform init downloads the provider plugin to .terraform/.
• ~> 5.0 means “any 5.x release” — gets patch fixes, avoids 6.x surprises.

The VM resource (main.tf)

resource "aws_instance" "vm" {
  ami           = data.aws_ami.ubuntu.id
  instance_type = var.instance_type
  key_name      = var.ssh_key_name
  vpc_security_group_ids = [aws_security_group.web.id]
  user_data     = local.user_data
  tags          = { Name = "url-shortener" }
}

One resource declaration ≈ one click in the EC2 console. user_data runs the Docker install script from L07 automatically on first boot — by the time apply returns the IP, the stack is already running.

The plan / apply loop

terraform init     # download providers (once per checkout)
terraform plan     # show diff — no changes applied
terraform apply    # apply the diff after confirmation
terraform destroy  # remove everything you created

• init is one-time per project. Re-run after editing versions.tf or the backend block.
• plan shows + create, - destroy, ~ in-place change, -/+ replace.
• apply runs plan again so the diff you approve is the diff you get.
• destroy is the cattle escape hatch: tear down, recreate from code.

State — the dirty secret

• Lose the file → orphaned cloud resources Terraform can’t manage.
• Two engineers apply against the same local state → state corruption.
• State is load-bearing. Never delete it. Never edit it by hand.
• Solution: remote state in S3 (next slides).

Local state: fine solo, dangerous shared

• For solo lab work, terraform.tfstate next to your .tf files is fine — if you don’t lose your laptop.
• The moment a second person needs to run apply, you need remote state.
• The moment you push state to a public repo, any secret value in your outputs leaks. Always add *.tfstate* to .gitignore.
• Module 3 starts with local state and migrates to S3 in Lab Step 6 — so you see both shapes.

Remote state with S3 + DynamoDB

terraform {
  backend "s3" {
    bucket         = "url-shortener-tfstate-acme"
    key            = "prod/terraform.tfstate"
    region         = "us-east-1"
    dynamodb_table = "url-shortener-tflock"
    encrypt        = true
  }
}

• S3 holds the state file (a few KB; versioned so you can roll back).
• DynamoDB holds a lock that prevents two applys from corrupting state simultaneously.
• Both resources are tiny — well within free-tier limits.

Chicken-and-egg: who creates the backend?

The S3 bucket and DynamoDB table can’t live in the same state — state has to already exist for that to work. Two clean solutions:

Migrating local state to S3

cd cloud-devops/sample-app/terraform/backend
terraform init && terraform apply -auto-approve   # creates bucket + table

cd ..
# Edit versions.tf — uncomment the backend "s3" { ... } block
terraform init -migrate-state                     # uploads local tfstate to S3
# Confirm 'yes'; the local file becomes a stub

After migration: wipe your laptop, clone the repo, run terraform init + plan from any machine with AWS credentials — same diff, same state.

What we build today

• sample-app/terraform/backend/ — bootstrap module; creates the S3 bucket (versioned, encrypted, public-access-blocked) + DynamoDB lock table.
• sample-app/terraform/ — main module: AMI lookup, security group (22/80/443), t3.micro, Elastic IP, user_data.sh that installs Docker and starts the L07 compose stack on first boot.
• First apply uses local state; Step 6 migrates to S3 with DynamoDB locking.
• Destroy + re-apply proves reproducibility: same infrastructure from code in ~90 seconds.

Scope limits — what L08 deliberately skips

• No Terraform modules library — we write inline; reusable modules come up in Module 4 with Helm.
• No multi-environment workspaces — the homework introduces workspaces; Module 4 makes them the default.
• No CI-driven apply — Module 5 covers Atlantis-style CI and ArgoCD image updates.
• No secrets management — .env still lives on the VM disk (same as L07); AWS Secrets Manager lands in Module 4.
• No RDS — Postgres is still a sidecar container; destroy wipes the data. Module 4 moves it to managed RDS.

Recap & what’s next

• Terraform replaces console clicks with code: declarative, idempotent, provider-agnostic.
• State is the dirty secret — S3 + DynamoDB solve the sharing and locking problems.
• The bootstrap module solves the chicken-and-egg: a tiny separate project with local state creates the bucket before the main module needs it.