How to Migrate AWS Organizations Without Breaking RAM Shares and Lake Formation

AWS Organizations migrations fail in a specific and quiet way: workloads keep running, but the control plane breaks. A Terraform deployment fails against a Transit Gateway. The stack is frozen mid-migration. The cause is something the architecture documentation warns about but the test environment almost never surfaces.

What Breaks and Why

When an AWS account moves between organizations, AWS RAM removes organization-bound principal associations from resource shares. The shares themselves do not disappear—but access to modify them through the control plane is severed. For a global payment processor migrating 382 accounts across 16 production waves, this failure mode appeared exactly once before production: on wave 1 of the pilot, which was the only wave that actually crossed an organization boundary. Fourteen non-production waves had not surfaced the issue because they moved accounts within the same test organization.

The affected services span the core of any multi-account architecture: Transit Gateway (network routing), Route 53 Resolver (DNS), AWS Private CA (certificate authority), EC2 prefix lists, Glue Data Catalog, and Lake Formation. Losing control-plane access to Lake Formation in particular creates compounding risk—Lake Formation permissions are managed by a service-created RAM share that cannot be manually recreated, and any changes attempted during the broken-share window risk permanent permission drift.

The Bridge-Share Pattern

The solution, developed with AWS, is a temporary parallel share that survives the organization move:

1. Before migrating each account, create a parallel RAM share for the same resource with allowExternalPrincipals: true and retainSharingOnAccountLeaveOrganization: true
2. Accept the invitation from the target account while still in the source organization, establishing an external association
3. Execute the account migration — the original organization-bound share breaks; the bridge share retains access
4. After migration, add the now-external account back to the original shares as an external principal
5. Validate that original shares are fully operational, then delete the bridge shares

The Lake Formation share requires particular care: the original AWS Lake Formation-created share is the durable, service-managed permission object. The bridge pattern preserves the permissions state during transit without attempting to recreate a service-managed object outside its intended lifecycle.

Operational Lessons from 382 Accounts

The migration team completed 378 of 382 accounts across 8 months, finishing before a Transitional Service Agreement deadline. Three critical practices enabled success at scale. First, monitoring AWS CloudTrail for DisassociateResourceShare calls provides the earliest signal that a migration wave has triggered the breakage. Second, a full inventory of RAM dependencies—across all resource types, in all accounts—must precede wave planning, not follow it. Third, test organization boundaries must mirror production organization boundaries, or the most important failure mode will only appear in the pilot wave.

For teams planning similar migrations, the AWS Architecture Blog case study includes the specific Terraform and CloudTrail patterns used at each stage.

Source: AWS Architecture Blog

Content created with AI assistance and reviewed for accuracy.