As part of my ongoing project to migrate a monolithic SaaS product to serverless, I’m setting up 2 new AWS accounts in order to:

host all new resources (API Gateway, Lambda, etc) that I'll be creating as part of the migration
gradually migrate existing resources from a non-isolated legacy account into the new accounts
ensure production resources can’t be accidentally interfered with
keep my dev workflow as efficient as possible

In this post, I’ll cover setting up an organizational structure, creating 2 accounts (dev/staging and production), creating IAM users and getting your CLI configured so that it's easy to manage going forward.

Organization Structure

I’ll be using AWS Organizations to create the accounts.

Note: If you’re in a corporate environment where you don’t have access to Organizations or the master account, then you’ll probably need to ask an admin in the master account to do this for you. You can then skip to the Setting up CLI Access section below.

I already have a master account in my company name, and an existing child account (referred to as the “legacy” account going forward) where all my current infrastructure is hosted. This legacy account contains resources for both dev/staging and production stages as well as some static websites which are unrelated to the product. My longer term goal is to move the appropriate resources into the new accounts and remove the legacy account altogether.

I’m also going to use an “Organizational Unit” for the product in case in the future I wish to apply policies across all accounts for this product but not touch accounts related to my other products.

Here’s what my org structure will look like:

🏠winterwindsoftware (master company account, billing goes here)
- 🔑 root (root user, MFA)
- 🗂autochart (product-specific Organizational Unit)
  - 🏠autochart_legacy
    - 🔑 root (root user, MFA)
    - 👥 sysadmins (IAM group, AdministratorAccess policy)
    - 👤 paul (IAM user, in sysadmins, MFA)
  - 🏠autochart_dev (NEW account, for dev and staging resources)
    - 🔑 root (root user, MFA)
    - 👥 sysadmins (IAM group, AdministratorAccess policy)
    - 👤 paul (IAM user, in sysadmins, MFA optional)
  - 🏠autochart_prod (NEW account, for production-only resources)
    - 🔑 root (root user, MFA)
    - 👥 sysadmins (IAM group, AdministratorAccess policy)
    - 👤 paul (IAM user, in sysadmins, MFA)

You can substitute autochart above with your product name when creating your own structure using the AWS Organizations Console.

To get started, login to the master account as the root user and create the 2 new accounts, entering in an account name and email address that you want to use for your child account root login.

🔥 Tip: NEVER use the email address associated with an existing personal Amazon.com account for your root login as there is currently no way of disconnecting it from the AWS account. To work around this, if you’re using a Gmail/Gsuite email address, you can use an alias address for each account by adding a plus sign after the first part of your address, e.g. paul+myproduct_dev@mycompany.com and paul+myproduct_prod@mycompany.com.

The steps below should be repeated for each new account.

🔥 Tip: I'd strongly recommend using a password manager to store and generate strong passwords for all the users you will be setting up. I use 1Password, which also provides 2 factor authentication functionality.

Logging in to new accounts for first time as root user

In order to login for the first time as the root user for your newly created account, you need to use the password reset process according to the AWS docs 🤔.

🔥 Tip: Before doing so, since you will be logging in to multiple AWS accounts, set up different browser profiles at this stage for your dev and prod users to make it easy to access each account concurrently and visually distinguish each account through a theme.

Activate Multi-Factor Auth for root user and create an individual IAM user

When you open the IAM Console as the root user, you will see a checklist like this:

You should now activate MFA on your root account and then complete the remaining steps.
Specifically, you should create a single user for yourself, using your own name. Ensure that you enable Programmatic and Console access for your user. I added this user to a newly created sysadmins group to which I added the AdministratorAccess policy.

Create account alias for console login

In the Dashboard of the IAM Console, you can create a friendly URL to login to the console. This saves you from having to enter the account ID in the login form each time.

Enable MFA for your production account’s IAM user

This isn’t absolutely necessary for your dev account, but since I granted full admin access to my IAM user, I want to ensure it’s as secure as possible.

To enable MFA for your IAM user, log out of the console as the root user, and log back in as the IAM user you created for yourself and go to Users -> your user -> Security Credentials tab and look for Assigned MFA Device.

You should use this IAM user for almost all your future console access.

Setting up CLI access

Although I’ve completed the above steps using the AWS Console, almost all my future configuration and resource management will be done programmatically, either via the AWS CLI, Javascript SDK or another Infrastructure as Code tool (e.g. Serverless framework or CloudFormation).

So the next step is to install the AWS CLI using the terminal. Then configure the CLI to use the access key and secret that were generated earlier for your IAM user. Don’t create a default profile as this could cause you to accidentally run a command against the wrong account. Instead create a named profile. I like to use the following convention for naming profiles <productname>_<environment>_<username>, e.g.

 aws configure —-profile myproduct_dev_paul
# ... enter your access ID, secret key and default region when prompted

Having separate profiles like this makes it easy to set up per-stage profiles inside your Serverless Framework services.

Creating more users

While I'm just a team of 1 working on my product, chances are there are other colleagues in your team who will need access. You can set them up as IAM users in the same way you created your own IAM user. You will need to make your own judgement as to what level of access you grant them. AdministratorAccess is probably fine for the dev account, but you may want to restrict access to the production account for some team members.

Unsubscribe from marketing emails

Finally, use this form to unsubscribe both email addresses used as your root users.

💌 If you enjoyed this article, you can sign up to my weekly newsletter on building serverless web apps in AWS.
You also might enjoy:

Originally published at winterwindsoftware.com.

How to set up AWS accounts for multiple product environments