Skip to content

Infrastructure as Code

What you’ll learn. Why infrastructure belongs in version control; how Terraform/OpenTofu works (providers, resources, the plan/apply cycle, the dependency graph, state and remote backends, modules, workspaces versus directories, drift and import); how Pulumi and Ansible differ; the immutable-infrastructure principle; and policy as code (OPA/Rego, Sentinel, Checkov). Pairs with Cloud Fundamentals.

Clicking through a cloud console produces infrastructure nobody can reproduce, review, or audit (“ClickOps”). IaC treats infrastructure definitions as code:

  • Reproducible: create identical staging and prod, or rebuild after a disaster (Incident & Reliability).
  • Reviewable: changes go through pull requests with a plan output.
  • Versioned and auditable: Git history is the change log.
  • Testable and automatable: CI validates, plans, and applies (CI/CD).
  • Documented: the code is the up-to-date description.

Two styles. Declarative (Terraform, CloudFormation, Kubernetes manifests): describe the desired end state; the tool computes the steps. Imperative/procedural (shell scripts, Ansible playbooks to a degree, Pulumi programs that generate a declared graph): describe steps or use a general-purpose language. Declarative tools are inherently idempotent: applying twice changes nothing the second time.

Terraform (HashiCorp, now IBM) pioneered the mainstream workflow. In 2023 HashiCorp moved Terraform from the MPL to the Business Source License; the community forked the last open-source version as OpenTofu (Linux Foundation, MPL 2.0), which is a drop-in for most configurations and has since added features of its own (for example, client-side state encryption). The HCL language, providers, and workflow described here apply to both; commands are terraform or tofu. Check licensing and feature differences for your organization.

*.tf files (HCL) --parse--> desired graph
| compare with state + refresh from real APIs
v
terraform plan ------------> diff: +create ~update -destroy
terraform apply ------------> call provider APIs in dependency order, update state
  • Provider: a plugin that knows an API (AWS, GCP, Azure, Kubernetes, GitHub, Cloudflare, Datadog…). Thousands exist.
  • Resource: a managed object (aws_instance, google_storage_bucket).
  • Data source: read-only lookup of existing things.
  • Variables/outputs/locals: inputs, return values, computed names.
  • State: Terraform’s record mapping each resource in your code to the real object ID plus its attributes.
versions.tf
terraform {
required_version = ">= 1.6"
required_providers {
aws = {
source = "hashicorp/aws"
version = "~> 5.0"
}
}
}
provider "aws" {
region = var.region
}
variables.tf
variable "region" {
type = string
default = "eu-west-1"
}
variable "env" {
type = string
description = "Environment name"
validation {
condition = contains(["dev", "staging", "prod"], var.env)
error_message = "env must be dev, staging, or prod."
}
}
main.tf
locals {
name = "myapp-${var.env}"
tags = {
Environment = var.env
ManagedBy = "terraform"
}
}
resource "aws_s3_bucket" "assets" {
bucket = "${local.name}-assets"
tags = local.tags
}
resource "aws_s3_bucket_public_access_block" "assets" {
bucket = aws_s3_bucket.assets.id # reference => dependency edge
block_public_acls = true
block_public_policy = true
ignore_public_acls = true
restrict_public_buckets = true
}
resource "aws_s3_bucket_versioning" "assets" {
bucket = aws_s3_bucket.assets.id
versioning_configuration {
status = "Enabled"
}
}
output "assets_bucket_arn" {
value = aws_s3_bucket.assets.arn
}
Terminal window
terraform init # download providers, configure backend
terraform fmt -recursive
terraform validate
terraform plan -out=tfplan
terraform apply tfplan
terraform destroy # careful

References like aws_s3_bucket.assets.id create edges in a dependency graph; Terraform creates independent resources in parallel and orders dependent ones. Use depends_on only for hidden dependencies.

# count: N copies indexed by number (fragile if you remove from the middle)
# for_each: one instance per key (stable identity; prefer it)
variable "buckets" {
type = set(string)
default = ["logs", "backups", "exports"]
}
resource "aws_s3_bucket" "b" {
for_each = var.buckets
bucket = "${local.name}-${each.key}"
}
resource "aws_instance" "app" {
# ...
lifecycle {
create_before_destroy = true
prevent_destroy = true # guard against accidents on stateful resources
ignore_changes = [tags["LastScan"]]
}
}

Newer features: moved blocks (refactor without destroy/create), import blocks (declarative import), check blocks (assertions), and removed blocks.

moved {
from = aws_s3_bucket.assets
to = aws_s3_bucket.static_assets
}

State is the most important and most dangerous part of Terraform. It maps config to real resources, stores metadata, and caches attributes for performance. It may contain secrets in plaintext (database passwords, generated keys), so treat it as sensitive.

Local state (terraform.tfstate on disk) is fine for experiments; it breaks for teams. Use a remote backend with locking so two applies cannot run concurrently and corrupt state:

terraform {
backend "s3" {
bucket = "mycompany-tfstate"
key = "prod/network/terraform.tfstate"
region = "eu-west-1"
encrypt = true
use_lockfile = true # S3-native locking in recent versions
# older setups: dynamodb_table = "tfstate-lock"
}
}

Alternatives: GCS, Azure Blob, Terraform Cloud/HCP, Terraform-compatible platforms (Spacelift, env0, Scalr, Atlantis for PR-based workflows). Enable bucket versioning for state recovery, restrict access tightly, and encrypt.

Split state by blast radius and change cadence: networking, data stores, and application layers each get their own state (prod/network, prod/data, prod/app), sharing information via outputs and terraform_remote_state or data sources. A single giant state makes plans slow and mistakes catastrophic; too many tiny states create coordination overhead.

State commands (use sparingly; always back up first):

Terminal window
terraform state list
terraform state show aws_s3_bucket.assets
terraform state mv aws_s3_bucket.a aws_s3_bucket.b # prefer `moved` blocks
terraform state rm aws_s3_bucket.legacy # stop managing, do not destroy
terraform import aws_s3_bucket.legacy my-existing-bucket

A module is a directory of .tf files with variables (inputs) and outputs, reusable like a function. The root configuration is itself a module.

infra/
modules/
vpc/ main.tf variables.tf outputs.tf
service/ ...
envs/
dev/main.tf
prod/main.tf
envs/prod/main.tf
module "vpc" {
source = "../../modules/vpc"
name = "prod"
cidr = "10.20.0.0/16"
azs = ["eu-west-1a", "eu-west-1b", "eu-west-1c"]
}
module "api" {
source = "../../modules/service"
name = "api"
subnet_ids = module.vpc.private_subnet_ids
min_size = 3
}

Registry modules (terraform-aws-modules/vpc/aws) save time; pin versions (version = "~> 5.0") and read what they create. Design guidelines: small focused modules with clear interfaces; avoid “god modules” with 80 variables and overly clever conditionals; don’t wrap a single resource in a module without added value; expose outputs generously; document inputs; version modules (Git tags) and use semantic versioning when sharing.

Environments: workspaces versus directories

Section titled “Environments: workspaces versus directories”

Workspaces (terraform workspace new staging) give one configuration multiple state instances in the same backend. They are convenient for ephemeral copies (per-PR environments) but hide which environment you are in (a classic way to apply to prod by accident), and they share identical code, so environments cannot diverge structurally.

Directory-per-environment (envs/dev, envs/prod, each calling shared modules with different variables and a separate backend key) is more explicit and is the common recommendation for long-lived environments; the cost is some duplication, reduced by modules and tools like Terragrunt. Whichever you choose, protect prod with separate credentials/roles, required approvals, and separate state.

Drift is divergence between the real world and the code, caused by console edits, other tools, or auto-scaling. terraform plan (refresh) reveals it: a plan with no code change that shows differences means drift. Responses: revert the real world (apply), or update the code to match, or ignore_changes for legitimately external attributes. Schedule a nightly plan in CI and alert on non-empty diffs; enforce “no console changes” through read-only human access in prod, with break-glass.

Importing brings existing resources under management:

import {
to = aws_s3_bucket.legacy
id = "my-existing-bucket"
}

terraform plan -generate-config-out=generated.tf can draft the configuration. Review it; generated code is verbose.

A typical PR workflow:

# .github/workflows/terraform.yml (excerpt)
on:
pull_request:
paths: ["infra/**"]
permissions:
id-token: write
contents: read
pull-requests: write
jobs:
plan:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: aws-actions/configure-aws-credentials@v4
with:
role-to-assume: arn:aws:iam::123456789012:role/tf-plan-readonly
aws-region: eu-west-1
- uses: opentofu/setup-opentofu@v1
- run: tofu fmt -check -recursive
working-directory: infra/envs/prod
- run: tofu init -input=false
working-directory: infra/envs/prod
- run: tofu validate && tofu plan -input=false -out=tfplan
working-directory: infra/envs/prod

Run plan on PRs (read-only role), post it as a comment, require review, then apply the saved plan on merge with a write role gated by an environment approval (CI/CD). Pin provider versions and commit .terraform.lock.hcl.

Never hardcode credentials in .tf files. Pass sensitive values via environment (TF_VAR_...), a secrets manager data source, or generate them in the cloud service. Mark variables sensitive = true (hides from output, not from state). Prefer federated/OIDC credentials for the provider itself. Encrypt state. See DevSecOps.

terraform validate and tflint (static), terraform test (native test framework, can run plan or apply against real or mocked providers), Terratest (Go, spins up real infrastructure), and policy checks (below). Ephemeral test accounts and automated cleanup keep this affordable.

Pulumi expresses infrastructure in general-purpose languages (TypeScript, Python, Go, C#, Java), keeping the same declarative engine model (desired state, diff, state backend). Programs build the resource graph.

import pulumi
import pulumi_aws as aws
bucket = aws.s3.BucketV2("assets", bucket="myapp-prod-assets")
aws.s3.BucketVersioningV2(
"assets-versioning",
bucket=bucket.id,
versioning_configuration={"status": "Enabled"},
)
pulumi.export("bucket_arn", bucket.arn)
Terminal window
pulumi up # preview + apply
pulumi preview

Pros: real loops, functions, types, unit tests, package reuse, IDE support. Cons: power invites over-abstraction and logic-heavy infrastructure that is hard to review; plan-time vs run-time values (Output types) take learning; a smaller community than Terraform’s. Related: AWS CDK (TypeScript/Python that synthesizes CloudFormation), CDK for Terraform (CDKTF, whose future depends on HashiCorp’s roadmap; check status), and Crossplane (Kubernetes-native: cloud resources as CRDs reconciled by controllers; see Kubernetes in Production).

Ansible is agentless configuration management over SSH (or WinRM/APIs), using YAML playbooks of tasks that call idempotent modules. It excels at configuring existing machines (packages, files, services), orchestrating rollouts, and network devices.

playbook.yml
- name: Configure web servers
hosts: web
become: true
vars:
app_port: 8080
tasks:
- name: Install nginx
ansible.builtin.package:
name: nginx
state: present
- name: Render config
ansible.builtin.template:
src: nginx.conf.j2
dest: /etc/nginx/conf.d/app.conf
mode: "0644"
notify: Reload nginx
- name: Ensure nginx running
ansible.builtin.service:
name: nginx
state: started
enabled: true
handlers:
- name: Reload nginx
ansible.builtin.service:
name: nginx
state: reloaded
Terminal window
ansible-playbook -i inventory.ini playbook.yml --check --diff # dry run
ansible-playbook -i inventory.ini playbook.yml
Terraform/OpenTofu Pulumi Ansible
Model Declarative, HCL, state Declarative engine, real languages, state Procedural tasks, idempotent modules, no state file
Best at Provisioning cloud resources Provisioning with complex logic or app-team ownership Configuring OS/software on hosts; ad-hoc orchestration
Weak at Complex logic, in-host configuration Ecosystem size, reviewability of clever code Tracking and destroying resources, drift detection

The classic split: Terraform provisions (VPC, VMs, databases), then something configures (Ansible, cloud-init, or, better, baked images). With containers and managed services, much of the configuration layer disappears into the image.

Mutable servers are patched and configured in place over their lifetime and accumulate drift (“snowflakes”; nobody can reproduce them). Immutable infrastructure never modifies a running server: to change anything, build a new image, deploy new instances from it, and discard the old ones (“cattle, not pets”).

Build images with Packer (VM images/AMIs), Dockerfiles (containers), or cloud-native image builders; deploy by replacing instances (auto-scaling group instance refresh, blue/green, Kubernetes rollout; see CI/CD). Benefits: no configuration drift, predictable rollbacks (redeploy the previous image), and the same artifact tested and shipped. Costs: image build pipeline, slower “tiny change” cycles, and state must live elsewhere (databases, object storage, volumes). Containers and Kubernetes embody this idea; extend it down through node images (Bottlerocket, Talos, Flatcar) where the OS itself is immutable and managed via API.

Guardrails encoded as automated rules that run on plans, manifests, or live resources, replacing manual review checklists.

  • OPA (Open Policy Agent) with the Rego language: a general policy engine. Conftest applies OPA to config files (Terraform plan JSON, Kubernetes YAML, Dockerfiles). OPA Gatekeeper and Kyverno enforce policies as Kubernetes admission controllers. Kubernetes also has built-in ValidatingAdmissionPolicy (CEL expressions).
  • HashiCorp Sentinel: policy framework for HCP Terraform/Enterprise.
  • Checkov, tfsec/Trivy, KICS, Terrascan: scanners with built-in rule sets for common misconfigurations (public S3 buckets, open security groups, unencrypted disks).
  • Cloud-native: AWS SCPs and Config rules, Azure Policy, GCP Organization Policy.

A Rego policy denying public S3 buckets evaluated against a Terraform plan JSON:

package terraform.s3
import rego.v1
deny contains msg if {
some rc in input.resource_changes
rc.type == "aws_s3_bucket_public_access_block"
rc.change.after.block_public_policy == false
msg := sprintf("%s must block public policies", [rc.address])
}
Terminal window
tofu show -json tfplan > plan.json
conftest test --policy policy/ plan.json
checkov -d infra/ --quiet

Apply policy in layers: developers’ IDE/pre-commit, CI on every PR (fail the build), admission control in the cluster, and detective controls on live infrastructure. Start in “warn” mode to calibrate false positives; give exceptions an owner and an expiry. This is shift-left for compliance (DevOps Culture, DevSecOps).

  • State loss or corruption: remote backend, versioning, locking, and restricted access.
  • Secrets in state and in plan files; treat both as sensitive artifacts.
  • Monolithic state and slow plans; or count indexes shifting and destroying resources (use for_each).
  • Unpinned providers and modules causing surprise changes.
  • Manual console changes causing drift; or apply from laptops with admin keys.
  • terraform destroy or prevent_destroy-less stateful resources (databases) in the same state as throwaway ones.
  • Over-abstraction: modules wrapping modules wrapping modules.
  • Treating plan as optional. Always read the plan; look for unexpected -/+ (replace) on stateful resources.
  • IaC makes infrastructure reproducible, reviewable, and auditable; declarative tools converge on a desired state and are idempotent.
  • Terraform/OpenTofu: providers talk to APIs, a dependency graph orders operations, and state maps code to reality; protect it with a locked, encrypted, versioned remote backend and split it by blast radius.
  • Modules are reusable units with explicit inputs and outputs; prefer for_each, pin versions, keep modules small.
  • Prefer directory-per-environment for long-lived environments; workspaces suit ephemeral copies. Detect drift with scheduled plans.
  • Pulumi brings real languages; Ansible configures hosts; the common pairing is “provision, then configure”, with immutable images shrinking the second step.
  • Policy as code (OPA, Checkov, Kyverno) automates guardrails in PRs and at admission.
  1. Hands-on. Write a Terraform/OpenTofu configuration (local provider or LocalStack/free-tier cloud) creating a bucket with versioning, using for_each over a set of names. Remove one name from the set and read the plan.
  2. Hands-on. Configure a remote backend with locking. Run two concurrent applies and observe the lock error.
  3. Conceptual. Explain why count is riskier than for_each when a list item is removed from the middle.
  4. Hands-on. Induce drift by changing a tag in the console; run plan, then choose between reverting and updating the code. Add a scheduled plan job to your CI.
  5. Design. Write a Conftest/Rego rule requiring every resource to have Environment and Owner tags.
Solutions (3)

count identifies instances by index ([0], [1], [2]). Removing the item at index 1 shifts the later items down, so Terraform sees [1] and [2] as changed and plans to destroy/recreate or update them. for_each keys instances by a stable string, so removing a key affects only that instance.

  • Yevgeniy Brikman, Terraform: Up & Running (3rd ed., 2022).
  • Kief Morris, Infrastructure as Code (2nd ed., 2020).
  • Official Terraform, OpenTofu, Pulumi, and Ansible documentation; the OpenTofu manifesto for background on the fork.
  • Open Policy Agent documentation (Rego language reference); Kyverno documentation.
  • Jeff Geerling, Ansible for DevOps (2020).