Networking — VPC and Subnets

Almost every AWS deployment starts with a network: a VPC, public and private subnets spread across availability zones, an internet gateway, a NAT gateway, and the route tables that wire them together. This is where most people first feel Terraform's value — a whole regional network from one config, reproducible in a second account — and first hit its sharp edges.

The sharpest edge is immutability. A VPC's CIDR block can't change without recreating the VPC, and a subnet's CIDR or availability zone can't change without recreating the subnet. Get the address layout wrong and the fix is a teardown, not an edit. So the lesson of this topic is as much about planning the network on paper as about the HCL.

The VPC and Its CIDR

A VPC is one aws_vpc resource with a CIDR block — the private IPv4 range every subnet carves from. Pick it deliberately: 10.0.0.0/16 gives you 65,536 addresses, enough room to subdivide across three or four AZs with space left over. The number that matters is that cidr_block forces replacement when changed, so a range you outgrow or that overlaps a network you later need to peer is not a tweak — it's a rebuild of everything inside it.

resource "aws_vpc" "main" {
  cidr_block           = "10.0.0.0/16"
  enable_dns_hostnames = true
  tags                 = { Name = "app-vpc" }
}

resource "aws_internet_gateway" "main" {
  vpc_id = aws_vpc.main.id
}

The internet gateway references aws_vpc.main.id rather than a hardcoded ID, so Terraform infers the dependency and creates the VPC first. Every resource in this topic is wired that way — the references are the dependency graph.

Subnets Across Availability Zones

Production subnets span at least two AZs so a single zone failure doesn't take the application down. Read the live zone list from the aws_availability_zones data source instead of hardcoding us-east-1a; the same config then works unchanged in eu-west-1. Iterate with for_each over a map keyed by AZ, and derive each subnet's range with cidrsubnet so the ranges never overlap by hand-arithmetic mistake.

data "aws_availability_zones" "available" {
  state = "available"
}

locals {
  # first three AZs, indexed 0,1,2 -> 10.0.0.0/24, 10.0.1.0/24, 10.0.2.0/24
  azs = { for i, az in slice(data.aws_availability_zones.available.names, 0, 3) : az => i }
}

resource "aws_subnet" "public" {
  for_each                = local.azs
  vpc_id                  = aws_vpc.main.id
  availability_zone       = each.key
  cidr_block              = cidrsubnet(aws_vpc.main.cidr_block, 8, each.value)
  map_public_ip_on_launch = true
  tags                    = { Name = "public-${each.key}" }
}

cidrsubnet(cidr, 8, n) adds 8 bits to the /16, producing /24 blocks, and the index n selects which one — so the function computes the ranges and they cannot collide. The reason to use for_each over a map rather than count over a list is identity: each subnet is keyed by its AZ name, so inserting or removing an AZ touches only that one subnet. With count, dropping the middle AZ renumbers every subnet after it and Terraform destroys and recreates them all.

Gateways, NAT, and Routing

Public subnets reach the internet through the internet gateway; private subnets reach out (for package updates, API calls) through a NAT gateway that lives in a public subnet and holds an Elastic IP. Routing is explicit: a route table per tier, a default route to the right gateway, and an association joining each subnet to its table. A common cost surprise is one NAT gateway per AZ for high availability — each one bills hourly plus per-GB, so a three-AZ layout means three NAT gateways running around the clock.

resource "aws_route_table" "public" {
  vpc_id = aws_vpc.main.id
  route {
    cidr_block = "0.0.0.0/0"
    gateway_id = aws_internet_gateway.main.id
  }
}

resource "aws_route_table_association" "public" {
  for_each       = aws_subnet.public
  subnet_id      = each.value.id
  route_table_id = aws_route_table.public.id
}

The association iterates over aws_subnet.public directly — each.value.id is each subnet's ID — so the set of associations always matches the set of subnets. Add an AZ and the matching association appears with it.

The VPC Module vs Hand-Rolling

Everything above is what the terraform-aws-modules/vpc module does for you, and for a standard topology it is the right call: it has handled the edge cases — flow logs, NAT-per-AZ toggles, IPv6, dozens of tag knobs — across thousands of deployments. Hand-roll the network only when you have a non-standard requirement the module fights you on, or when the learning is the point. Reaching for the module is not laziness; it is declining to re-debug a solved problem.

Immutability Gotchas

The attributes that force replacement are the ones tied to the network's addressing: the VPC cidr_block, and a subnet's cidr_block and availability_zone. Changing any of them destroys and recreates the resource, and recreating a subnet that an ASG or load balancer sits in is an outage. This is why the CIDR layout is a design decision made once, up front, and written down — not something you iterate on in production.