Skip to content

0022: Migration of AdAction AWS Accounts into AdGem AWS Organization

STATUS

  • Proposed

CONTEXT

Currently, AdAction AWS resources reside under the AdAction AWS Organization, while AdGem maintains a separate AWS Organization. To consolidate governance, billing, compliance, and infrastructure management, we need to migrate AdAction accounts into the AdGem AWS Organization.

This migration will streamline security controls, consolidate billing, simplify AWS Identity Center integration, and reduce overhead in maintaining multiple org-level configurations.

However, migrating AWS accounts between organizations involves Root User actions, careful sequencing, and updates to organizational dependencies such as Service Control Policies (SCPs), AWS Config, CloudTrail, and IAM roles.

Considered Options

  • Leave accounts as-is in AdAction Org
  • Avoids migration complexity, but keeps split billing/governance.
  • Manually replicate resources into new AdGem accounts
  • High effort, risk of drift, downtime, and cost.
  • Migrate accounts directly from AdAction Org → AdGem Org
  • Supported by AWS, preserves workloads with no downtime, requires careful sequencing.

DECISION

We will migrate all AdAction AWS accounts into the AdGem AWS Organization using AWS’s supported “Invite from new org → Leave old org → Accept invite” workflow. To reduce time as a standalone account, AdGem will send invitations before accounts leave AdAction. The process will be planned in phases, with extensive pre-migration discovery, testing, and phased execution to minimize risk.

CONSEQUENCES

Positive Outcomes

  • Consolidated governance and billing under AdGem Org.
  • Unified compliance and auditing with single AWS Identity Center.
  • Reduced overhead of managing two AWS Organizations.
  • No downtime to workloads during migration.

Negative Outcomes

  • Requires Root User credentials and temporary standalone billing setup.
  • Short-term risk of misaligned SCPs, IAM trust policies, or identity mappings.
  • Additional migration effort for org-level features (e.g., CloudTrail, AWS Config).

Risks & Mitigations

  • Risk: Accounts cannot leave/join due to Root User access or prerequisites.
  • Mitigation: Verify Root credentials/MFA, phone verification, and payment method per account.
  • Risk: Loss or drift of org-level controls (SCPs, StackSets) during migration.
  • Mitigation: Inventory current controls; reapply SCPs/guardrails in AdGem immediately post-join; plan StackSets cleanup/redeployment.
  • Risk: IAM roles/policies reference the old Org ID (e.g., aws:PrincipalOrgID).
  • Mitigation: Search/replace Org ID in IAM/SCPs during cutover; peer review diffs.
  • Risk: SSO/Identity Center users lose access.
  • Mitigation: Stage Identity Center configuration and assignments in AdGem ahead of migration.

Impact on CDK/CI Pipelines

What stays the same - Account IDs don’t change; account-scoped resources (CodePipeline, CodeBuild, CloudFormation stacks, S3, ECR, etc.) remain. - Workloads continue to run during migration.

What can break - Org-based trust & conditions: IAM/SCP conditions using aws:PrincipalOrgID and any hard-coded AdAction Org ID. - Cross-account roles: Trusts that allow the old org’s management or tooling accounts (e.g., OrganizationAccountAccessRole). - Identity Center assignments: SSO role mappings from AdAction won’t carry over. - StackSets: Org-managed StackSets from AdAction won’t target accounts after they leave that org.

Mitigations - Search/replace Org ID in IAM policies, trust policies, and SCPs; re-issue with AdGem Org ID. - Recreate cross-account assume-role trusts from the AdGem tooling accounts; remove legacy AdAction trusts. - Pre-stage Identity Center permission sets and assignments in AdGem; validate - If pipelines depended on org-level StackSets, recreate those StackSets in AdGem and re-target the migrated accounts. - One option to reduce disruption during and after migration is to move our CI/CD pipelines from AWS CodePipeline into GitHub Actions.
- This approach decouples CI/CD from AWS Organizations and org-scoped roles.
- Requires setting up OIDC federation and per-account deploy roles.

Verification checks - From the pipeline account, sts:AssumeRole into each target account succeeds. - A no-op CDK diff and CodePipeline dry-run (or manual run on a sandbox stack) completes without role/permission errors.

Billing Considerations

What happens during migration - When an account leaves AdAction Org, it temporarily becomes a standalone payer account.
- The Root user must have a valid credit card and phone verification in place.
- Charges during this period are billed directly to that standalone account.
- When the account joins AdGem Org, all new charges consolidate into AdGem’s management account.

What does not migrate - Billing history, invoices, budgets, and cost & usage reports from AdAction Org do not transfer.
- These must be exported before migration if needed for compliance, audits, or financial reporting.

What carries over - Active Reserved Instances (RIs) and Savings Plans stay with the migrating account and continue to apply after the move.
- Any account-level tax settings, credits, or promotional codes remain attached to the account.

Post-migration actions - Re-create budgets, cost categories, and cost allocation tags under AdGem Org.
- Validate billing alerts and dashboards in AdGem after migration.
- Open an AWS Support case if RIs or Savings Plans need to be reallocated across accounts in the new org.

NOTES

Migration Plan (Phases)

Phase 1: Discovery & Planning

  • Inventory all AdAction accounts, workloads, and dependencies. , including CodePipeline setups.
  • List integrations with IdPs, AWS SSO/Identity Center, third-party tools.
  • Identify org-level controls and dependencies: SCPs, CloudTrail, AWS Config, delegated admin registrations, and StackSets.
  • Confirm Root access, MFA, phone verification, and valid payment method on each account.
  • Export org-level billing reports and any organization-scoped artifacts.

Phase 2: Pre-Migration Setup

  • In AdGem Org (management account):
  • Prepare baseline SCPs, CloudTrail, AWS Config, and Identity Center setup.
  • Send organization invitations to each AdAction account (do this before accounts leave AdAction).
  • In each AdAction account:
  • Identify and plan to remove cross-org access roles (e.g., OrganizationAccountAccessRole) that permit the old management account to assume access after the move.
  • Catalog IAM policies and trust policies that reference the old Org ID.

Phase 3: Account Removal (AdAction Org → Standalone)

  • Using the Root User of each AdAction account, choose Leave Organization.
  • Ensure the account operates as a standalone account (payment method, phone verification, tax/support settings as needed).
  • If the account is a delegated administrator for any integrated service, deregister first.
  • Note: Org-level CloudTrail/Config/SCPs from AdAction stop applying once the account leaves. Account-level resources continue to run; StackSets-managed resources might require cleanup/redeployment later.

Phase 4: Account Invitation Acceptance (Join AdGem Org)

  • From each standalone account (Root User), accept the pending invitation sent earlier by AdGem.
  • Validate the account now appears under AdGem Org (root), then move it to the appropriate OU.

Phase 5: Post-Migration Reconfiguration

  • Reapply SCPs in AdGem Org; move the account into the intended OU hierarchy.
  • Enable organization-level CloudTrail and AWS Config in AdGem; align account with baseline guardrails.
  • Update IAM roles and trust relationships to use the new Org ID; delete any legacy access roles from AdAction.
  • Recreate AWS Identity Center assignments and permission sets; validate access paths.
  • Review billing tools (budgets, cost categories, alarms) and update cost allocation tags.

Phase 6: Validation & Cutover

  • Validate workloads, access paths, and guardrails.
  • Peer review IAM/SCP changes.
  • Decommission remaining references to the AdAction Org.

Migration Flow (Visual Aid)

flowchart TD A[AdAction Account in AdAction Org] -->|AdGem sends invite first| B[Leave AdAction Org - Root User Action] B --> C[Standalone AWS Account] C --> D[Accept Invite from AdGem Org - Root User] D --> E[Move to Target OU + Reapply SCPs] E --> F[Re-establish CloudTrail/Config + Validate IAM/SSO] F --> G[Final Validation & Cutover] style A fill:#ff9800,color:#0d1117 style C fill:#fff3e0,color:#0d1117 style D fill:#2196f3,color:#0d1117 style G fill:#c8e6c9,color:#0d1117

Future Considerations

  • Automate account enrollment into AdGem Org using CDK or Control Tower.
  • Evaluate Control Tower landing zone for baseline governance.
  • Decommission AdAction Org once all accounts are migrated.

References

Original Author

  • Fabian Leon

Approval date

Approved by

Appendix

Appendix A — Pre-Migration Checklist (per account)

  • [ ] Root user can sign in; MFA enabled; phone verified.
  • [ ] Valid payment method on file (standalone readiness).
  • [ ] Not a delegated admin for any AWS service; if yes, deregister.
  • [ ] Export any account-specific billing/Cost Explorer data if needed.
  • [ ] Inventory policies/trusts using AdAction Org ID or aws:PrincipalOrgID.
  • [ ] Identify cross-account roles trusted by AdAction management/tooling accounts.
  • [ ] Confirm AdGem invitation is visible (sent before leaving AdAction).

Appendix B — Cutover Checklist (per account)

  • [ ] Leave AdAction Org (Root).
  • [ ] Accept AdGem invite (Root); move into target OU.
  • [ ] Apply baseline SCPs; confirm guardrails active at OU.
  • [ ] Enable org-level CloudTrail and AWS Config coverage (AdGem).
  • [ ] Update IAM trust policies to new AdGem Org ID; remove AdAction trusts.
  • [ ] Recreate Identity Center assignments; verify principal access.
  • [ ] Pipelines: assume-role tests, CDK diff, and one safe deploy path green.
  • [ ] Cost allocation tags/budgets/alerts confirmed in AdGem.

Appendix C — Post-Migration Audit (batch)

  • [ ] All accounts present in correct OUs; SCP evaluation sample passes.
  • [ ] Central logging/Config aggregators show new accounts.
  • [ ] No residual references to AdAction Org ID in IAM/SCPs.
  • [ ] Remove any obsolete StackSets/roles from AdAction.