Create new AWS accounts with Organizations and Terraform

AWS Organizations

It’s important to understand what AWS Organizations service is in order to create new AWS accounts with Terraform. Even if you don’t want to create new AWS accounts with Terraform and instead create them manually, knowing AWS organizations features will help you to be a top notch cloud engineer! The introduction video of what AWS Organizations is the best place to start.

Besides the rich functionality it provides, the next best thing about is that it’s 100% free! Here’s an official link to the AWS documentation. Be sure to read the AWS Organizations best practices too.

AWS Organizations is not enabled by default. Once we create the resource via Terraform it will be enabled.

AWS Organizations Permissions

At minimum and possibly more you will need the following IAM permissions. Remember this needs to be on your master account. Here’s the architecture I’m following.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ManageOrganizations",
      "Effect": "Allow",
      "Action": [
        "organizations:CreateOrganization",
        "organizations:EnableAWSServiceAccess",
        "organizations:DisableAWSServiceAccess",
        "organizations:DescribeOrganization",
        "organizations:ListRoots",
        "organizations:ListAccounts",
        "organizations:ListAWSServiceAccessForOrganization"
      ],
      "Resource": "*"
    }
  ]
}

AWS Organizations Terraform Code

If you have not used Terraform before I would encourage you to start at Terraform and Terragrunt introduction. Otherwise continue. Remember this needs to be applied on your master account.

# Provides a resource to create an AWS organization.
resource "aws_organizations_organization" "this" {

  # List of AWS service principal names for which 
  # you want to enable integration with your organization
  aws_service_access_principals = [
    "cloudtrail.amazonaws.com",
    "config.amazonaws.com",
  ]

  feature_set = "ALL"
}

After applying just the code above we have enabled AWS Organizations… and it’s requesting an email confirmation. Be sure to check your inbox and confirm within 24 hours.

Only after we confirmed the email address we can now invite existing AWS accounts to join our organization or create new ones!

Import an existing AWS Organizations

If you have already created/enabled AWS Organizations with the AWS CLI or through the console you do have the option to import and manage with Terraform going forward.

# If you using Terraform only
terraform import aws_organizations_organization.my_org o-1234567

# If you use Terragrunt
terragrunt import aws_organizations_organization.my_org o-1234567

Create new AWS account

The Terraform code below will create a new member aka AWS account in the organization.

resource "aws_organizations_account" "dev" {
  # A friendly name for the member account
  name  = "cloudly-engineer-dev"
  email = "somethingdev@gmail.com"

  # Enables IAM users to access account billing information 
  # if they have the required permissions
  iam_user_access_to_billing = "ALLOW"

  tags = {
    Name  = "cloudly-engineer-dev"
    Owner = "Waleed"
    Role  = "development"
  }
}

After applying this Terraform code you will see a new account member in the AWS Organizations. Sadly, you will not get a set of credentials automatically.

Getting the new AWS Accounts password

Since this account was created from AWS Organizations you have to navigate to the AWS console to sign in as the root account. Then enter your new accounts email address and then select Forgot Password. Then enter the captcha code and you will receive an email on setting a new password for your new AWS account. Ensure to setup MFA after logging in to secure your account login.

Code structure

Here’s the way I structured my code for this project. I use Terragrunt on top of Terraform. Master is my only account/environment in this project.

aws/
   org
    ├── README.md
    ├── main.tf
    ├── master
    │   ├── inputs.yml
    │   ├── terragrunt.hcl
    │   └── vars.tf
    └── terragrunt.hcl

# main.tf
provider "aws" {
  region  = var.aws_region
  profile = var.aws_cli_profile
}

terraform {
  backend "s3" {}
}

# Provides a resource to create an AWS organization.
resource "aws_organizations_organization" "this" {

  # List of AWS service principal names for which 
  # you want to enable integration with your organization
  aws_service_access_principals = [
    "cloudtrail.amazonaws.com",
    "config.amazonaws.com",
  ]

  feature_set = "ALL"
}

resource "aws_organizations_account" "dev" {
  # A friendly name for the member account
  name  = "cloudly-engineer-dev"
  email = "somedev@gmail.com"

  # Enables IAM users to access account billing information 
  # if they have the required permissions
  iam_user_access_to_billing = "ALLOW"

  tags = {
    Name  = "cloudly-engineer-dev"
    Owner = "Waleed"
    Role  = "development"
  }
}

That’s it for now. In future posts I’ll continue to cover more of AWS Organizations by creating OU’s, Service policies and more so be sure to subscribe!