{"id":80734,"date":"2026-07-29T13:13:10","date_gmt":"2026-07-29T07:43:10","guid":{"rendered":"https:\/\/www.tothenew.com\/blog\/?p=80734"},"modified":"2026-07-30T15:54:52","modified_gmt":"2026-07-30T10:24:52","slug":"terraform-state-migration-seamlessly-moving-from-aws-s3-to-google-cloud-storage","status":"publish","type":"post","link":"https:\/\/www.tothenew.com\/blog\/terraform-state-migration-seamlessly-moving-from-aws-s3-to-google-cloud-storage\/","title":{"rendered":"Terraform State Migration: Seamlessly Moving from AWS S3 to Google Cloud Storage"},"content":{"rendered":"

Introduction:<\/strong><\/p>\n

What if the single source of truth for your entire infrastructure lived in the wrong cloud?
\nFor years, our Terraform state lived in an AWS S3 bucket while our infrastructure increasingly ran on Google Cloud Platform. That split created cross-cloud dependencies, IAM complexity, and a growing mismatch between where we managed infrastructure and where we stored its state.<\/p>\n

Terraform state is the record of what Terraform believes exists in the real world. Move it incorrectly, and the next Terraform apply can propose destructive changes against production.<\/p>\n

This post covers how we migrated hundreds of Terraform projects from AWS S3 to Google Cloud Storage (GCS), how we verified each migration, and the challenges we solved along the way.<\/p>\n

Why this matters:<\/h2>\n

Operational alignment\u00a0\u2014 State storage should live in the same cloud as the resources being managed.
\nOrg structure\u00a0\u2014 We operate multiple organizational tiers, each with its own GCS state bucket.
\nSafety at scale\u00a0\u2014 With 100+ CI-managed Terraform projects, ad-hoc\u00a0terraform state mv\u00a0commands were not an option.<\/p>\n

What you’ll learn in this article:<\/h2>\n

Our migration architecture and phased approach
\nStep-by-step instructions for copying state and switching backends
\nHow we automated validation across multiple repos
\nChallenges we faced: path mismatches, stale datasources, and state drift and how we solved them<\/p>\n

Understanding Our Starting Point:<\/h2>\n

Before (S3):<\/p>\n

\"alt=""\"<\/a>

S3 backend config<\/p><\/div>\n

After (GCS):<\/p>\n

\"\"

GCS backend config<\/p><\/div>\n

Key convention: the S3 key maps verbatim to the GCS prefix.<\/p>\n

Migration Targets:<\/strong><\/h2>\n

\"\"<\/p>\n

Some consumer projects that had already landed in the enterprise bucket were later moved to the consumer bucket via a separate\u00a0GCS-to-GCS\u00a0migration driver.<\/p>\n

Migration Architecture: Four Phases<\/strong><\/h2>\n

\"\"<\/p>\n

We treated state migration as a pipeline, not a one-shot operation. Each Terraform project progresses through four distinct phases: Each phase is independently verifiable, which was critical when migrating at scale via pull-request-driven CI (e.g., Atlantis).<\/p>\n

Phase 0: Inventory and Classification
\n<\/strong>
\nBefore touching state, we built\u00a0validate_state_migration.py\u00a0to scan both repos and label every Terraform directory:<\/p>\n

\"alt=\"<\/a>

validate state migration<\/p><\/div>\n

This became our living migration dashboard and primary completion gate.<\/p>\n

 <\/p>\n

Phase 1: Copy State Files (S3 \u2192 GCS)
\n<\/strong>
\nInstead of per-project\u00a0gsutil cp, we built Terraform migration drivers:<\/p>\n

state-migration\/main.tf\u00a0\u2014 v1 (frozen, lookup-only)
\nstate-migration-v2\/main.tf\u00a0\u2014 v2 (new paths added here)
\ngcs-state-migration\/main.tf\u00a0\u2014 GCS-to-GCS (enterprise \u2192 consumer)
\nCore pattern:<\/p>\n

data “aws_s3_object” “s3_to_gcs_migration” {
\nfor_each = toset(local.migration_paths)
\nbucket = local.source_bucket
\nkey = each.value
\n}<\/p>\n

resource “google_storage_bucket_object” “s3_to_gcs_migration” {
\nfor_each = toset(local.migration_paths)
\nbucket = local.destination_bucket
\nname = “${each.value}\/default.tfstate”
\ncontent = data.aws_s3_object.s3_to_gcs_migration[each.value].body
\ndeletion_policy = “ABANDON”
\nlifecycle { ignore_changes = [content, crc32c, generation, md5hash] }
\n}
\nDesign choices:<\/p>\n

deletion_policy = “ABANDON”\u00a0\u2014 destroying the driver never deletes production state.
\nignore_changes\u00a0\u2014 driver doesn’t fight live state updates after initial copy.
\nOne-time copy, not continuous sync.
\nSteps:\u00a0add S3\u00a0key\u00a0to\u00a0migration_paths\u00a0\u2192 PR \u2192 CI apply \u2192 verify with\u00a0gsutil ls.<\/p>\n

Important: State changes between copy and backend switch cause drift. Delete the stale GCS object and re-run migration if needed.<\/p>\n

Phase 2: Switch Backend
\n<\/strong>
\nUpdate\u00a0backend “s3”\u00a0to\u00a0backend “gcs”\u00a0in the project’s\u00a0main.tf. Open a PR \u2014 CI runs\u00a0terraform init -reconfigure\u00a0and\u00a0terraform plan.\u00a0Zero unexpected changes is the validation gate.\u00a0We kept the old S3 backend commented out for easy rollback.<\/p>\n

Phase 3: Migrate Datasources
\n<\/strong>
\nMany projects read upstream state via\u00a0terraform_remote_state\u00a0\u2014 those also pointed at S3. We automated rewrites with a script that:<\/p>\n

Changes\u00a0backend = “s3”\u00a0\u2192\u00a0“gcs”, maps bucket, converts\u00a0key\u00a0\u2192\u00a0prefix, drops\u00a0region
\nFollows relative module sources into shared\u00a0implementation\/\u00a0dirs
\nSafety gate:\u00a0skips datasources whose upstream state isn’t copied yet
\nA two-phase MR workflow (whitespace baseline commit, then actual rewrite) ensured CI plans showed datasource-only diffs with no resource changes.<\/p>\n

Phase 4: GCS-to-GCS (Org Split)
\n<\/strong>
\nProjects that landed in the enterprise bucket but belonged to the consumer tier used the same driver pattern reading from one GCS bucket and writing to another.<\/p>\n

How to Verify Migration: <\/h2>\n\n\n\n\n\n\n
Level<\/strong><\/th>\nCheck<\/strong><\/th>\nPast Criteria<\/strong><\/th>\n<\/tr>\n
Object<\/span><\/td>\ngsutil stat<\/span><\/td>\nState file at\u00a0{prefix}\/default.tfstate<\/span><\/td>\n<\/tr>\n
Plan<\/span><\/td>\nterraform plan<\/span><\/td>\n0 creates, 0 destroys, 0 changes<\/span><\/td>\n<\/tr>\n
Inventory<\/span><\/td>\nValidator<\/span><\/td>\nThe label is *-CLEAN (not MIGRATED-BE)<\/span><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

A plan showing creates or destroys means a stale state or wrong prefix\u2014stop and investigate.<\/p>\n

Challenges We Faced:<\/h2>\n

1. Legacy path mismatches
\nNot every S3 key matched its GCS prefix. We maintained explicit key-mapping tables (e.g., infrastructure\/db\/app\/development \u2192 infrastructure\/db\/development). Blind copying by directory name silently copies wrong or empty state.<\/p>\n

2. State drift
\nApplies between copy and backend switch stale the GCS copy.
\nFix: delete the stale object, re-copy, and immediately merge the backend PR.
\nPrevention: freeze applies during the copy-to-switch window.<\/p>\n

3. Stale datasources
\nProjects stuck at MIGRATED-BE had split-brain dependencies. The migration script’s safety gate ensures upstream state exists in GCS before rewriting references.<\/p>\n

4. Shared implementation modules
\ndevelopment\/, staging\/, production\/ dirs often only contain a backend and module { source = “..\/implementation” }. Datasource reads live in the shared module; the script follows relative sources recursively.<\/p>\n

5. Transition limbo
\nTreat MIGRATED-BE as blocking. Migration isn’t done until the label reads CLEAN.<\/p>\n

6. Scale
\nHundreds of directories across two repos migrated in team-owned batches: register paths \u2192 copy \u2192 switch backend \u2192 migrate datasources \u2192 verify CLEAN.<\/p>\n

7. Premigration state surgery
\nSome projects needed moved\/removed blocks before switching backends (security boundary changes, phantom addresses to avoid destruction on removal).<\/p>\n

End-to-End Migration Flow (Summary):
\n\"\"<\/p>\n

Conclusion:<\/strong><\/p>\n

Migrating Terraform state at scale is about building a repeatable, verifiable pipeline \u2014 not running a single command. Terraform-driven bulk copy, phased backend switching, automated data source migration, and inventory-based validation let us migrate hundreds of projects safely through CI with zero state-corruption incidents.<\/p>\n

Key takeaways:<\/strong><\/p>\n

Map S3\u00a0key\u00a0to GCS\u00a0prefix\u00a0verbatim; override legacy mismatches explicitly.
\nNever switch a backend without a clean plan.
\nMigrate in phases, each independently gateable.
\nAutomate inventory with labels (CLEAN,\u00a0MIGRATED-BE,\u00a0NOT-MIGRATED).
\nProtect the state with deletion_policy = “ABANDON” and ignore changes.
\nStart with inventory, migrate in small batches, and treat every\u00a0terraform plan\u00a0as your safety net.<\/p>\n

Have you migrated Terraform state across cloud providers?\u00a0Share your experience in the comments \u2014 we’d love to compare notes.<\/p>\n","protected":false},"excerpt":{"rendered":"

Introduction: What if the single source of truth for your entire infrastructure lived in the wrong cloud? For years, our Terraform state lived in an AWS S3 bucket while our infrastructure increasingly ran on Google Cloud Platform. That split created cross-cloud dependencies, IAM complexity, and a growing mismatch between where we managed infrastructure and where […]<\/p>\n","protected":false},"author":1982,"featured_media":0,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"iawp_total_views":0},"categories":[5877],"tags":[1853,248,5084,8733,6362,1587,4030,8734,6087,8732,1585],"aioseo_notices":[],"_links":{"self":[{"href":"https:\/\/www.tothenew.com\/blog\/wp-json\/wp\/v2\/posts\/80734"}],"collection":[{"href":"https:\/\/www.tothenew.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.tothenew.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.tothenew.com\/blog\/wp-json\/wp\/v2\/users\/1982"}],"replies":[{"embeddable":true,"href":"https:\/\/www.tothenew.com\/blog\/wp-json\/wp\/v2\/comments?post=80734"}],"version-history":[{"count":5,"href":"https:\/\/www.tothenew.com\/blog\/wp-json\/wp\/v2\/posts\/80734\/revisions"}],"predecessor-version":[{"id":80965,"href":"https:\/\/www.tothenew.com\/blog\/wp-json\/wp\/v2\/posts\/80734\/revisions\/80965"}],"wp:attachment":[{"href":"https:\/\/www.tothenew.com\/blog\/wp-json\/wp\/v2\/media?parent=80734"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.tothenew.com\/blog\/wp-json\/wp\/v2\/categories?post=80734"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.tothenew.com\/blog\/wp-json\/wp\/v2\/tags?post=80734"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}