Infrastructure as CodeInfrastructure as Code

Part of the DevOps Roadmap knowledge base.

Overview

Infrastructure as Code (IaC) is the practice of defining infrastructure — networks, compute, databases, DNS, IAM policies — in machine-readable definition files that live in version control, instead of provisioning it by clicking through consoles or running ad-hoc commands. The infrastructure definition becomes the source of truth: reviewable in pull requests, testable in pipelines, reproducible across environments, and auditable through git history.

IaC solves the classic operations pathologies: snowflake servers nobody dares touch, environment drift between staging and production, “it worked when I set it up” tribal knowledge, and disaster recovery plans that exist only on paper. When infrastructure is code, rebuilding an environment is a terraform apply away, and every change has an author, a reviewer, and a diff.

For DevOps engineers, IaC is foundational: it is how CI/CD pipelines get environments to deploy into, how platform teams offer self-service infrastructure, and how organizations enforce security and cost policy at the point of provisioning rather than after the fact.

The mental model: desired state and reconciliation

The core idea that makes IaC powerful is desired-state reconciliation. You write down what the world should look like; the tool inspects what the world actually looks like; it computes and applies the difference. This is the same loop that powers Kubernetes controllers and GitOps. Once you internalize it, every IaC tool becomes a variation on one question: “where is the desired state stored, and how does the tool know the current state?” Terraform stores current state in a state file; CloudFormation stores it in AWS; Kubernetes stores it in etcd; Crossplane stores it in etcd and reconciles continuously. The differences in ergonomics all flow from that one design choice.

Fundamentals

Declarative vs imperative

• Declarative — you describe the desired end state (“one VPC, three subnets, an EKS cluster with two node groups”) and the tool computes the actions needed to get there. Terraform, CloudFormation, and Kubernetes manifests are declarative. Reconciliation and drift detection come naturally.
• Imperative — you describe the steps (“create VPC, then create subnet, then…”). Shell scripts and raw cloud CLI calls are imperative. Order and error handling are your problem; re-running is rarely safe.

Modern tools blur the line: Pulumi and CDK let you write imperative-looking code (loops, functions, classes) that produces a declarative desired state which the engine then diffs and applies. The imperative code runs to build a graph; the graph is what gets reconciled. This is why a Pulumi program is still idempotent even though it looks like a script.

Provisioning vs configuration

They complement each other: Terraform creates the VM; Ansible (or a baked image, or a container) makes it useful. In cloud-native setups, configuration increasingly disappears into container images and managed services, leaving provisioning as the dominant IaC activity.

Terraform core workflow

• Providers — plugins that map HCL resources to real APIs (aws, azurerm, google, kubernetes, github, datadog — thousands exist in the registry). terraform init downloads them and records exact versions in .terraform.lock.hcl, which you commit.
• State — Terraform records what it created in a state file, mapping config to real-world resource IDs. The plan is a three-way diff: configuration (what you want) vs state (what Terraform thinks exists) vs actual cloud reality (discovered by refresh).
• Plan/apply — plan computes an execution plan (create/update/replace/destroy); apply executes it. Save the plan to a file (terraform plan -out=tfplan) and apply that exact file, so CI applies precisely what was reviewed.
• Modules — reusable, parameterized groups of resources (module "vpc" { source = "terraform-aws-modules/vpc/aws" ... }). Modules are how organizations encode golden paths.
• Workspaces — multiple state files for one configuration (useful for ephemeral or per-developer environments; many teams prefer separate root directories per environment instead, for stronger isolation and to avoid the “wrong workspace” foot-gun).
• Remote state & locking — state stored in a shared backend (S3, Azure Blob, GCS, Terraform Cloud/HCP) with locking (native S3 lockfile, DynamoDB, or backend-native) so two applies cannot corrupt state concurrently.

The plan verbs — read them carefully

Every line in a plan is one of these, and the dangerous ones deserve a full stop during review:

The phrase forces replacement next to an attribute is the single most important thing to notice in a plan: it means an in-place change is impossible and Terraform will delete and recreate the resource. For a database or persistent volume, that is a data-loss event hiding in a routine-looking diff.

Example Terraform snippet

terraform {
  required_version = ">= 1.9"
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
    }
  }
  backend "s3" {
    bucket       = "acme-terraform-state"
    key          = "prod/network/terraform.tfstate"
    region       = "ap-southeast-1"
    use_lockfile = true          # native S3 state locking (TF 1.10+)
    encrypt      = true
  }
}

module "vpc" {
  source  = "terraform-aws-modules/vpc/aws"
  version = "~> 5.0"

  name            = "prod-vpc"
  cidr            = "10.0.0.0/16"
  azs             = ["ap-southeast-1a", "ap-southeast-1b"]
  private_subnets = ["10.0.1.0/24", "10.0.2.0/24"]
  public_subnets  = ["10.0.101.0/24", "10.0.102.0/24"]

  enable_nat_gateway = true
  single_nat_gateway = true

  tags = { Environment = "prod", ManagedBy = "terraform" }
}

resource "aws_s3_bucket" "artifacts" {
  bucket = "acme-prod-artifacts"
  tags   = { Environment = "prod" }
}

# Guard a stateful resource against accidental destruction
resource "aws_db_instance" "main" {
  identifier     = "acme-prod-db"
  engine         = "postgres"
  instance_class = "db.t3.medium"
  # ... other args ...
  lifecycle {
    prevent_destroy = true       # apply fails rather than deleting the DB
  }
}

output "vpc_id" {
  value = module.vpc.vpc_id
}

Wiring layers together with remote state

Large estates split into layered stacks (network → data → app), each with its own state. Downstream layers read upstream outputs via a remote state data source:

data "terraform_remote_state" "network" {
  backend = "s3"
  config = {
    bucket = "acme-terraform-state"
    key    = "prod/network/terraform.tfstate"
    region = "ap-southeast-1"
  }
}

resource "aws_instance" "app" {
  subnet_id = data.terraform_remote_state.network.outputs.private_subnet_ids[0]
  # ...
}

This keeps blast radius small: a change to the app layer cannot accidentally destroy the network, and each plan stays fast because it only refreshes its own resources.

Key Concepts

Tool landscape

When to reach for which:

• Single cloud, want the vendor’s blessed tool and no extra state to manage → CloudFormation/CDK (AWS) or Bicep (Azure).
• Multi-cloud, or you want the largest provider ecosystem and community → Terraform/OpenTofu.
• Your team wants real language features (loops, unit tests, abstractions) more than a DSL → Pulumi or CDK.
• You are building an internal platform where app teams request infra through Kubernetes-style APIs and want continuous reconciliation → Crossplane.
• You need to avoid the BUSL license or want state encryption out of the box → OpenTofu.

The Terraform / OpenTofu license split

In 2023 HashiCorp relicensed Terraform from MPL (open source) to BUSL (source-available, with restrictions on competing commercial use). The community forked the last MPL version as OpenTofu, now a Linux Foundation project. For most users the two are drop-in compatible (tofu replaces terraform), and OpenTofu has since shipped features Terraform lacks, notably client-side state encryption. When choosing, weigh: ecosystem/tooling maturity (Terraform still larger), licensing constraints for your business, and which features you need.

State management pitfalls

State is Terraform’s Achilles heel — most production incidents with IaC trace back to it:

• Secrets in state. State stores all attributes in plaintext, including database passwords, generated keys, and private keys. Encrypt the backend, restrict access tightly (the state bucket is as sensitive as your credentials), and prefer references to secret managers over inline secrets.
• Concurrent applies without locking. Two pipelines applying at once corrupt state. Always use a locking backend; never disable locking to “fix” a stuck lock without confirming no apply is actually running (terraform force-unlock is a last resort, not a habit).
• Manual edits and console drift. Changes made in the console are invisible until the next plan, which may then try to revert them. Detect drift regularly (terraform plan on a schedule); make out-of-band changes an incident, not a habit.
• Monolithic state. One giant state file makes every plan slow and every mistake catastrophic. Split state by environment and by blast radius (network / data / app layers), wiring layers together with remote state data sources or explicit outputs.
• Refactoring without moved/import. Renaming a resource or moving it into a module looks like destroy+create to Terraform. Use moved blocks (safe, in-code, reviewable), import blocks, or terraform state mv to refactor without destroying anything.
• Lost or corrupted state. Losing the state file orphans resources (they exist in the cloud but Terraform no longer knows about them). Version the backend bucket, enable object versioning, and back it up so you can roll back a bad state write.
• terraform apply with no saved plan in CI. If CI re-plans at apply time, it may apply something different from what was reviewed (the world changed in between). Apply a saved plan file.

Example: safe rename with a moved block

# You renamed aws_instance.web → aws_instance.frontend.
# Without this block, Terraform destroys "web" and creates "frontend".
moved {
  from = aws_instance.web
  to   = aws_instance.frontend
}

Terraform treats this as “same resource, new address” — no destroy, no downtime.

Testing IaC

Layered validation, cheapest first:

1. Static checks — terraform fmt -check, terraform validate, linters (tflint), and security scanners (trivy, checkov, tfsec) catch syntax errors, deprecated patterns, and misconfigurations (public S3 buckets, open security groups, unencrypted volumes) before any API call.
2. Plan review — run terraform plan in CI on every PR and post the plan as a comment; a human (and a policy engine) reviews exactly what will change. Treat -destroy lines and forces replacement with suspicion.
3. Policy as code — evaluate plans against organizational rules automatically:
   • OPA / Rego (with conftest or OPA directly) — open-source, general-purpose policy engine.
   • Sentinel — HashiCorp’s policy language, integrated into Terraform Cloud/Enterprise.
   • Example rules: “all resources must be tagged with Owner”, “no security group may allow 0.0.0.0/0 on port 22”, “instance types limited to an approved list”, “S3 buckets must have encryption enabled”.
4. Integration tests — spin up real (or ephemeral) infrastructure and assert on it with Terratest (Go) or terraform test (native, HCL-based since Terraform 1.6), then destroy. Slowest and most expensive, so reserve for reusable modules and critical paths.

# policy/deny_public_ssh.rego (OPA/conftest)
package terraform.security

deny[msg] {
  r := input.resource_changes[_]
  r.type == "aws_security_group_rule"
  r.change.after.cidr_blocks[_] == "0.0.0.0/0"
  r.change.after.to_port == 22
  msg := sprintf("%s allows SSH from the internet", [r.address])
}

deny[msg] {
  r := input.resource_changes[_]
  r.type == "aws_s3_bucket"
  not r.change.after.server_side_encryption_configuration
  msg := sprintf("%s must have encryption enabled", [r.address])
}

Run it against a JSON plan: terraform show -json tfplan | conftest test -.

Native terraform test example

# tests/vpc.tftest.hcl
run "creates_private_subnets" {
  command = plan

  assert {
    condition     = length(module.vpc.private_subnets) == 2
    error_message = "expected exactly two private subnets"
  }
}

Policy as code: OPA vs Sentinel

Best Practices

1. Store all IaC in version control and change it only via pull requests. The git history is your audit log; the review is your change-approval process; nothing changes production without a diff.
2. Use remote state with locking and encryption from day one. Local state on a laptop is a single point of failure, a collaboration blocker, and an unencrypted secrets file waiting to leak.
3. Never put secrets in code or rely on state secrecy alone. Pull secrets from a manager (Vault, AWS Secrets Manager, SSM) at apply/run time; treat the state backend as sensitive regardless, because generated secrets still land in state.
4. Split state by environment and blast radius. Small, layered states make plans fast, reviews readable, and mistakes survivable; wire layers with remote state outputs.
5. Pin versions everywhere. Terraform/OpenTofu version, provider versions, and module versions — and commit the .terraform.lock.hcl lock file — so plans are reproducible and an upstream release cannot silently change your infrastructure.
6. Run plan in CI and require it to be reviewed before apply — then apply the saved plan. Nobody should apply from a laptop against shared environments, and CI should apply exactly the plan that was approved.
7. Enforce policy as code. Tagging, encryption, network exposure, and cost rules belong in OPA/Sentinel gates that block a bad plan, not in wiki pages nobody reads.
8. Prohibit console changes to managed resources. Drift turns your source of truth into fiction; detect it on a schedule and reconcile deliberately rather than letting the next unrelated apply revert someone’s manual fix.
9. Design modules with small, stable interfaces. Expose a few well-chosen variables and outputs; resist the “module that takes 80 variables” that is harder to use than raw resources.
10. Refactor with moved/import blocks, never by editing state blindly. Make renames and restructures reviewable in code so they cannot turn into an accidental destroy.
11. Prefer immutability for anything replaceable, and guard the rest. Replace stateless instances rather than mutating them; keep data-bearing resources (databases, volumes) in their own state with prevent_destroy lifecycle guards.
12. Scrutinize every forces replacement and destroy in a plan. These are where data loss and downtime live; a plan review that skims past them is not a review.
13. Practice recovery. Periodically rebuild a full environment from code in a sandbox account — that is the only real test of whether your IaC is complete and your state is recoverable.
14. Scan IaC for security misconfigurations in the pipeline. Checkov/Trivy/tfsec findings are far cheaper to fix pre-apply than post-breach, and they catch the mistakes humans miss in review.

References

• roadmap.sh — DevOps Roadmap
• Terraform documentation
• Terraform Registry (providers & modules)
• Terraform — state
• Terraform — test framework
• OpenTofu documentation
• Pulumi documentation
• AWS CloudFormation documentation
• AWS CDK documentation
• Azure Bicep documentation
• Crossplane documentation
• Open Policy Agent
• Conftest
• HashiCorp Sentinel
• Checkov
• tflint
• Terratest
• Book: Terraform: Up & Running — Yevgeniy Brikman
• Book: Infrastructure as Code — Kief Morris