Blog

Terraform: An Introduction to Infrastructure as Code

By Aaron F. January 21st, 2023

Introduction

A few years ago I wrote a short piece about Terraform here on the blog. Reading it back, it was fine, but it never really said what the thing is actually like to use. I've spent the years since managing every piece of my infrastructure with it, across a handful of projects and cloud accounts, so I wanted to write the introduction I would actually hand to someone today.

Infrastructure as Code (IaC) is exactly what it sounds like. Instead of clicking through a cloud console to create servers, databases, and DNS records by hand, you describe what you want in plain text files and let a tool build it. Terraform, from HashiCorp, is the tool I reach for. You write a description of your infrastructure, Terraform works out the difference between that description and what actually exists, and then it makes reality match the file.

That one idea, make reality match the file, is the whole game. It changes how you work more than you would expect.

What it looks like

Terraform is written in HCL (HashiCorp Configuration Language), which is deliberately plain. Here is a complete, real example that creates a storage bucket on AWS:

That is the entire thing. You never tell Terraform how to create the bucket, only that you want it to exist. The aws provider knows how to talk to AWS, and the resource block declares the thing you want. Edit the file, and Terraform edits the bucket to match.

The workflow

Day to day, working with Terraform is really just three commands:

The one in the middle is the reason I trust it. terraform plan shows you, line by line, exactly what it is about to create, change, or destroy before it touches a single thing. Nothing gets provisioned by surprise. After enough years of clicking around consoles and hoping, having a tool tell you "here are the two things I am going to change, and nothing else" is genuinely calming.

State: the part that actually matters

Here is the concept most introductions skip, and it is the one that catches people out. Terraform keeps a state file, a record of everything it manages and how your config maps to the real resources. That file is how it knows the bucket in your config is that bucket over in AWS, and not a brand new one to go and create.

A few things follow from that, and they are worth taking on board early:

• The state file is the source of truth about what Terraform owns. Treat it as precious.
• Do not keep it on your laptop for anything real. Store it remotely, in an S3 bucket or Terraform Cloud, so it is shared, backed up, and locked while someone is applying.
• If someone changes a managed resource by hand in the console, Terraform notices the drift on the next plan and offers to put it back. That is a feature, not a nuisance.

Why it is worth it

Once your infrastructure lives in code, a pile of benefits comes along almost for free:

• It is reviewable. Infrastructure changes go through the same pull requests & git history as the rest of your code. You can see who changed what, and why.
• It is repeatable. The same config can stand up an identical staging & production environment, or rebuild everything from scratch if you ever have to.
• It is honest. The files are the documentation. There is no "someone set this up two years ago and nobody remembers how," because the how is right there in front of you.
• It is everywhere. The same tool and workflow manage AWS, Cloudflare, GitHub, DNS, and hundreds more services through providers.

Where to start

Do not try to codify your entire world on day one. Pick one small, low-risk thing you already run, a DNS record, a single bucket, a static site, and describe it in Terraform. Run plan, read every line, run apply. Then change something and watch it reconcile. That loop, edit then plan then apply, is the whole skill, and it clicks fast.

The old version of this article ended with a tidy "in conclusion" paragraph. I will skip it. Terraform is one of the few tools I have adopted and never once wanted to walk back. If you manage anything in the cloud, it is worth an afternoon of your time.

Topics: Amazon Web Services, Cloud Infrastructure, Platform Engineering