AWS Organizations is a way for you to organize your accounts and have a hierarchy not only for bills to roll up to a single paying account, but also to setup a way to add new accounts programatically.

For the purposes of this discussion, take a look at my AWS lab account structure.

From the AWS Organizations Console we can see the account structure as well.

I need to create a new account in a new OU under my master billing account. This can be accomplished through the console, but it can also be done through the AWS CLI, which is what I’ll do here. NOTE: This can be done through the API as well which can be really useful for automating the building of new accounts.

Permissions Prep

Before we start issuing commands there are some pre-requisites that need to be met first. To begin, we’ll need to have a login that has permissions for Organizations:CreateAccount. Since I’ll be doing additional work such as moving accounts around and Creating OUs I’ve created an AWS policy for OrganizationalAdmins and given my user full permissions on the organizations service.

I also want to mention that our CLI connection must be made to the root account within AWS organizations.

Create A New Account

Now that we’ve got our permissions taken care of, open up a terminal and connect to the Master Billing Account as the user who has permissions to create accounts and modify organizations.

From here we’re going to run our AWS CLI command to create a new account.

aws organizations create-account -email user@domain.com --account-name [name]

Here is a screenshot of what happened when I created my account.

This command starts the account creation build and as you can see some return data comes back and shows the status is “IN_PROGRESS”.

If we want to check the status of the account creation we can run the following command and insert the requestID which was returned in the create-account command.

aws organizations describe-create-account-status --create-account-request-id [requestid]

Here is my screenshot of the describe command. We can see that when I checked it again, the status was “SUCCEEDED”

At this point the account has been created. You should get an email to the address specified with further instructions but also, the account should be built with a role named “OrganizationAccountAccessRole” which will allow you to do a role switch into that account from the root account.

Create a New OU

Now that the account has been created we need to create a new OU. To do this from the AWS CLI we’ll use the “create-organizational-unit” command, but first we need to find out the ID of the root.

To find the root ID run the following:

aws organizations list-roots

Once you run that command it should return a list of the root accounts. In my case there is only one root and we’re looking for an id that begins with “r” and has at least 4 characters after it.

We will now create the new OU by providing it a new name and also passing in the root as the parent.

aws organizations create-organizational-unit --parent-id [parentID] --name [Name]

Here is a screenshot of my commands for both listing the roots and adding a new OU under the root.

Move Account into new OU

Now that the account and OU are created, we can move the account into the appropriate OU. To do this we’ll use the “move-account” command. You’ll need to pass in the account ID, parent ID (the root we found earlier beginning with “r”) and the OU ID which was returned in the create-organizational-unit command that begins with “ou”

aws organizations move-account --account-id [accountID] --source-parent-id [rootID] -destination-parent-id [OU ID]

Here is a screenshot of my commands in the CLI.

Results

Now if we look back in our AWS Console we’ll see our new account created and listed under the appropriate OU just as we were hoping for.