Terraform · Cloud architecture · 9 min read ·
Adopting Terraform on a brownfield estate without breaking production
Importing an existing cloud estate into Terraform is a sequencing problem. The order that keeps production safe, and the mistakes that make people give up halfway.
Greenfield Terraform is easy: write the module, apply it, done. Brownfield is where most teams are, and it fails for a predictable reason: they start by importing the most important thing, the plan shows a hundred differences, and nobody dares apply. Six months later there is a terraform/ directory nobody trusts.
The way through is to treat import as a controlled migration with an order, a review step and a definition of done for each piece.
Decide the layout before importing anything
Where state lives and how it is split determines the blast radius of every apply for years. Three rules that hold up:
- One state per environment per domain. Networking, identity, shared platform and each application area get their own state. A change to a dev app cannot touch the production VNet if they are not in the same state.
- Remote state with locking from day one. Azure Storage or S3 with DynamoDB. Local state is how two engineers overwrite each other.
- Modules for the things you will build more than once. Not for everything. A module with one caller is indirection, not reuse.
Write this down as a short design before the first import. It is the document the next engineer needs.
Import in dependency order, lowest risk first
Import the things that other things depend on, but start with the least dangerous of them:
- Resource groups, tags, naming — trivially importable, immediately useful for the plan to reference.
- Networking — VNets, subnets, route tables, NSGs. Read-only in effect; getting the plan to zero here builds confidence.
- Identity and policy — managed identities, role assignments, policy definitions.
- Shared platform — registries, key vaults, DNS zones, monitoring.
- Workloads — last, one at a time, with the owning team.
For each: terraform import (or an import block), then terraform plan, then reconcile the plan to zero before moving on. A non-zero plan means the code does not describe reality; leaving it is how trust dies.
Reconcile, do not force
Differences in the plan fall into three kinds:
- Attributes Terraform manages that the code got wrong. Fix the code.
- Attributes set outside Terraform that should stay that way (a tag another system writes). Use
ignore_changesdeliberately and comment why. - Reality that is wrong. The rare and valuable finding. Decide with the owner whether to fix reality or codify it.
Never apply a plan you have not read line by line during adoption. The goal of this phase is zero diffs, not a green apply.
Put the apply behind a workflow before production is in scope
By the time production resources are under management, applying from a laptop must already be impossible. The minimum:
- Plan on every pull request, with the plan output posted for review.
- Apply only from the main branch, by the pipeline, with an environment approval for production.
- Policy checks (OPA/Conftest, Sentinel, or cloud-native policy) that fail the plan for the mistakes that matter: public storage, open security groups, missing tags.
- A federated identity for the pipeline. No long-lived cloud credentials in CI secrets.
Detect drift continuously
Adoption is done when drift is reported, not discovered. A scheduled terraform plan per state that alerts on non-empty output is enough to start. It also tells you, honestly, whether people are still clicking.
The mistakes that cause abandonment
- Starting with the biggest workload. Start with networking.
- Importing without reconciling. A plan with diffs is not done.
- One giant state. It makes every apply frightening.
- Forcing a green apply by adding
ignore_changesto everything. That is not management; it is a decorative file. - Doing it alone. The owning teams know what the diffs mean.
If you want an independent view of where an estate stands before you begin, a Terraform / IaC assessment produces a coverage and drift report with an import order.
Keep reading
Migration · Cloud architecture · 7 min
Migration by disposition, not by lift
A cloud migration that treats every workload the same ends up moving the problems with the servers. How to classify an estate into dispositions, plan the waves, and keep the business running while the ground moves.
Cloud architecture · Security · 7 min
Landing zones before the first workload
The account structure, identity, network and guardrails that every later decision rests on. What a landing zone has to settle, what it can leave open, and the order that avoids rebuilding it in year two.