Planning account migrations between AWS organisations

As more companies move to the cloud with AWS, many are finding success in adopting multi-account architecture to house their various workloads. AWS Organisations is a feature of AWS which facilitates the grouping of accounts into various organisation units (OU), each with their own security boundaries. It also offers consolidating billing for all child accounts.

As your business grows, you may need to move accounts between AWS organisations. For instance, this could happen after an acquisition, where there is a need to group existing AWS accounts under a single organisation for billing, operational or compliance reasons.

Before moving an account from one AWS organisation to another, there are a number of checks which should be performed to ensure workloads continue to operate without interruption. This article is a non-exhaustive guide on some of the steps which need to be taken before you begin your account migration journey.

Prepare your target organisation

Before moving an account to your target AWS organisation, you must first check the organisation has not reached its total account quota. By default, organisations have a quota of 10 accounts. Pending invitations also count towards this quota.

To increase this limit, an AWS support request must be raised.

Analyse account resources

Within AWS, you will encounter various types of policies which govern access to resources in your accounts. These such policies are:

Identity policies which are attached to IAM users, roles or groups Service control policies which are attached to accounts or organisation units (OUs) Resource-based policies which are attached to resources

Before moving an account out of its current AWS organisation we must pay special attention to resource-based policies. A resource-based policy is typically used to control which principals can access the resource the policy is attached to. A common use-case is to allow cross-account access to the resource.

Consider the following policy attached to a customer managed KMS key.

Note the second statement in the policy allows any principal (denoted by the "AWS": "*") to perform the listed actions IF the Condition block evaluates to true. Here, the condition contains aws:PrincipalOrgID which further restricts access to only principals within the AWS organisation matching the organisation id o-abcde12345.

If an account in your AWS organisation has workloads dependent on the aforementioned KMS key, the workloads will lose access once the account is removed from the organisation. Naturally, this would need to be rectified before the account is moved.

There are more than 20 AWS services which support resource-based policies. Before moving your accounts, you must first find and remediate any resource-based policies containing aws:PrincipalOrgID. This account analysis can be automated using tools such as check-aws-resources-for-org-conditions or aws-resource-based-policy-collector (the latter written by me).

Cloudformation StackSets auto-deployment

A StackSet enables deploying a Cloudformation template as a stack across multiple accounts and regions. Each stack created from a StackSet is called a stack instance.

StackSets can be created with auto-deployment enabled. As new accounts are added to an organisation or OU, a new stack instance is automatically created inside the new account.

If a stack instance is created automatically from a StackSet when an account is added to an organisation or OU, you may be wondering what happens when an account is removed from the organisation or OU? This is controlled by the StackSet's RetainStacksOnAccountRemoval property. If set to false, a stack created by the StackSet will be deleted when the account is removed from the organisation or OU! I'm sure you can imagine this would be an unpleasant surprise if stacks containing business-critical resources suddenly get deleted just because you moved an account, even just to another OU under the same organisation.

Before moving accounts, even within the current organisation, you must first check that no StackSets exist with RetainStacksOnAccountRemoval set to false. If found the StackSets must be updated to either disable auto-deployment entirely or to set RetainStacksOnAccountRemoval to true to prevent the stack from being deleted.

AWS RAM

AWS RAM allows the sharing of resources from one account into other accounts. Resource types that are RAM sharable include Transit Gateways, VPC subnets and Route53 resolver rules, among several others.

When a resource is shared via AWS RAM, it can be shared either explicitly with single accounts via invitation, or implicitly with the parent AWS organisation, meaning all accounts under the organisation gain access to the shared resource automatically. It is this organisation-wide sharing which may be problematic when moving an account containing resources shared this way, as once an account leaves the organisation, the resource may no longer be accessible.

Unfortunately this is something which needs close inspection and remediation varies depending on resource type. It is also important to note that several RAM sharable resources are only sharable within the same organisation! You can find a complete list of RAM sharable resources here.

Cloudtrail

Cloudtrail is enabled on all AWS accounts by default. It works by recording all API actions taken against resources in the account as a Cloudtrail event. The previous 90 days worth of events are always viewable and available for download. In addition to this, there is an option to record events to an S3 Bucket by creating a (somewhat confusingly named) Cloudtrail trail. A trail can be created on a per-account basis or organisation-wide as an organisation trail.

If your source organisation is configured with an organisation trail, logs will no longer be delivered to the trail's S3 bucket once removed from the organisation. If your target organisation already has an organisation trail, the new account will be picked up automatically once it joins the target organisation with logs now being delivered to a bucket within the target organisation.

If your target organisation does not have an organisation trail but the source organisation does, you will either need to create an organisation trail in the target organisation, or alternatively, create an account-level trail in your source account before moving it to the target organisation.

Savings plans and reserved instances

If the organisation you are moving accounts from has any cost saving discounts such as savings plans or reserved instances, you may incur unexpected costs after moving resources to your target organisation as you will start accruing cost at the non-discount rate. Savings plans and reserved instances are not transferable, so you may lose money on prior upfront payments made. Be sure to reach out to your AWS account manager to discuss any cost saving options prior to migrating accounts.

Conclusion

Moving accounts between AWS organisations is challenging and requires careful planning. Before diving head-first into an account migration, be sure to take the time to assess your accounts and resources to reduce the likelihood of any interruption to your workloads come migration day.