Don't panic, organize

As your cloud workloads grow, the much desired fine-granularity you had in mind when you started becomes more and more difficult to keep. This rule applies to companies and teams of any shape and size. Thankfully and thoughtfully, AWS created a bunch of services that come in handy when adding some shape and structure to cloud topology starts to feel like a necessity. In this article, we will take a closer look at one of such services, namely AWS Organizations, and show how it can be used to help encapsulate your projects/apps/accounts.

TL;DR

• use the combined power of AWS Organizations and Terraform to keep your infra clean and orderly
• all code is here

Game plan

In this article, I'll be using Terraform to show you how to create:

• an AWS Organization
• sample IAM groups and users
• an Organizational Unit (OU)
• two AWS accounts, one for development and the other for production, under the OU
• a Service Control Policy curbing some of the permissions of OU's accounts

Prerequisites

If you want to follow along, you'll need to have:

• access to the email address associated with AWS account that will become the master account of your organization
  + NB, at the time of writing AWS supported only one root in an organization‍
• programmatic access, with adequate permissions, to your AWS account
• Terraform v0.12 or higher installed on your local machine‍
• Keybase configured locally and/or GPGSuite

Preparation

Before we can commence with provisioning any organization - related resources, we need to do some prep work. Let's kick-off by creating a folder for our project:

Within that folder we are going to set up the minimal Terraform configuration required and then run the initialization command:

+aws-organizations-example/provider.tf

For the sake of simplicity, the Terraform state will be stored locally. This is not recommended,but fear not, you may refer to the example provided on Github and see how S3 can be used as a backend.

+ running terraform init

Since we have laid the ground work, we are now ready to commission our organization.

Creating an AWS Organization

First, we'll create a module for organizations:

+aws-organizations-example/organizations/main.tf

+aws-organizations-example/organizations/variables.tf

+aws-organizations-example/organizations/outputs.tf

Next, we'll initialize it:

+aws-organizations-example/main.tf

+ must run terraform init again

And finally, we are going to run terraform plan and, if it goes without a hitch, terraform apply:

+ running terraform plan

+ running terraform apply

When the process completes, you'll see the following message in the AWS Management Console for AWS Organizations:

Now, log in to your mailbox, check for a message from AWS and confirm the ownership of the email account:

Splendid! You've just created your first AWS Organization:

Now, let's get down to creating users, groups and accounts.

Setting up groups and users

We'll commence, by creating a module for iam-groups. They will allow us to assign our users to either the administrators or the developers group (or both if we wished, though that would not make much sense):

+aws-organizations-example/iam-groups/main.tf

+aws-organizations-example/iam-groups/variables.tf

Using the above pattern, you can easily add a plethora of other groups depending on your particular needs, e.g. a group for Accountants with access only to the billing section of AWS, etc..

Next, a module for iam-users would be recommended. So, let's add it now:

+aws-organizations-example/iam-users/main.tf

+ aws-organizations-example/iam-users/variables.tf

+ aws-organizations-example/iam-users/outputs.tf

Finally, to make it all work add the following lines to the aws-organizations-example/main.tf:

Initialize the modules:

+ run terraform plan followed by terraform apply:

You can grab the output and safely pass it to the user, who can then decrypt the sensitive bits (e.g. the encrypted-secret-access-key), using their PGP in the following manner:

NB, keybase pgp decrypt can be swapped with pgp --decrypt

That’s a wrap of part 1. In the next and final one, we’ll talk about Organizational Units and Service Control Policies. See you there!