What is brownfield Terraform migration?
Brownfield Terraform migration means adopting new modules or standards for infrastructure Terraform already controls, without destroying or recreating what exists. It typically involves swapping module sources and versions, then checking the plan before applying.
How it works
Terraform records every resource in state under an address, such as module.logs.aws_s3_bucket.this[0], rather than under the module source it was created from. As long as the replacement module keeps every resource at its existing address, editing source involves no state moves: terraform plan diffs those same resources against the new configuration. If the addresses do change, the migration needs moved blocks or terraform state mv. In both cases, study the plan before applying, since a changed argument can still force a replacement.
The source-line swap
Because compliance.tf modules mirror the structure of terraform-aws-modules, editing the source URL is the only code change required. No state migration is needed, and the backend configuration stays untouched.
module "logs" {
- source = "terraform-aws-modules/s3-bucket/aws"
+ source = "soc2.compliance.tf/terraform-aws-modules/s3-bucket/aws"
version = "~> 5.0"
}The procedure:
- Choose a framework; this determines the endpoint.
- Authenticate using
terraform loginor a token. - Edit the
sourceline. - Run
terraform init -upgrade. The-upgradeflag is not optional. - Run
terraform planand resolve any validation errors the controls surface. - Apply.
Take on one module at a time. compliance.tf and upstream modules can coexist within a single configuration.
What can still force recreation
A few controls set values that are hard to modify on a resource that already exists. Enabling encryption at rest on a live RDS instance or ElastiCache cluster requires a snapshot-restore or a new cluster. Retention for objects already stored in an S3 bucket has to be set on each existing object version, either one at a time or via S3 Batch Operations, and turning on encryption for an existing Redshift cluster kicks off a migration that leaves the cluster read-only until it finishes. When your resources already carry these settings, the migration is clean. When they do not, disable that control for the moment and handle the retrofit as a separate piece of work.
To roll back, put the earlier source line and version back, run terraform init -upgrade, then review and apply the plan. Whatever settings were already applied to AWS remain in effect until that apply runs.