Brownfield Adoption at Scale

Almost nobody starts with Terraform. Teams start with years of console-built infrastructure — a live estate that someone clicked into existence and that now runs production — and have to bring it under management without downtime and without a big-bang rewrite. Brownfield adoption is the strategy for that migration: importing existing infrastructure in safe increments, drawing state boundaries as you go, and accepting that this is a phased program measured in months, not a weekend project.

This is the capstone of the course because it pulls together everything before it. Import brings resources under management, modules and state organization decide where they live, and the core workflow verifies each step. Adoption is those tools applied to a real, running estate that you are not allowed to break.

The Brownfield Reality

The defining constraint is that recreation is off the table. You cannot destroy production and let Terraform rebuild it — the resources exist, they hold state and traffic, and a rebuild means an outage and risk nobody will sign off on. So adoption is import, not creation: you bring the resources Terraform didn't make under its management exactly as they are. The estate is also messy in ways greenfield work never is — undocumented dependencies, resources nobody remembers creating, and configurations that don't match any standard. The plan has to survive contact with that mess.

Incremental Import Strategy

The unit of adoption is a small, reviewable batch. Use import blocks to declare which existing resources to bring under management, lean on -generate-config-out to get a starting configuration rather than hand-writing every argument, and then iterate the configuration until plan reports no changes. That no-change plan is the proof: it means the configuration now matches reality exactly, so the first real apply won't touch anything. A batch isn't done until its plan is clean.

# declare the existing resources to adopt — reviewable in the plan
import {
  to = aws_vpc.main
  id = "vpc-0abc123"
}

import {
  to = aws_subnet.app
  id = "subnet-0def456"
}

# generate a starting config, then refine until plan is clean:
#   terraform plan -generate-config-out=generated.tf
#   ...edit until "No changes. Your infrastructure matches the configuration."

The import blocks live in version control and show up in the plan, so a batch is a reviewed change like any other. Once a batch is imported and verified, the import blocks have done their job and can be removed. Then you move to the next batch — the estate comes under management one safe increment at a time.

Drawing State Boundaries During Migration

Import forces a decision you can't defer: which state does each resource go into. The temptation is to dump everything into one giant state to get it over with, and that bakes in the worst possible structure — a single high-blast-radius state where any change risks everything and every apply is slow. Draw boundaries as you import instead, aligned to blast radius and ownership: separate state for networking, for the data tier, for each application, for each environment. The migration is the one cheap chance to get these boundaries right, because moving a resource between states later is surgery you'd rather not do.

Prioritization and Sequencing

Not everything needs importing at once, and the order matters. Bring the high-churn, high-risk infrastructure under management first — the resources that change often, where drift and undocumented manual edits cause the most pain, and where having a reviewed plan delivers the most value. Stable, rarely-touched resources can wait; there's little benefit to rushing a thing nobody ever changes under management. Sequencing by risk and churn means the migration pays back from the earliest batches instead of after the whole estate is done.

Organizational Change

The hardest part isn't technical. Bringing infrastructure under Terraform but letting teams keep changing it in the console guarantees constant drift — every manual edit is a change Terraform doesn't know about, and the next plan either reverts it or fights it. Adoption only sticks when teams stop using the console on managed resources and route every change through code. That is a habit and a governance change, not a Terraform feature, and it's the difference between adoption that holds and an estate that drifts back to where it started. Pair the technical migration with the organizational one or the technical work erodes.

That organizational discipline is also where the whole course lands. Everything from the first plan to this last page rests on a single commitment: that the code is the source of truth, and reality is made to match it — not the other way around.