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 in your management/root account.

{
  "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 management/root 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",
    "sso.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. But in order to achieve well-architected structure you must place your accounts in OUs. This way the Service Control Policies (SCPs) will be applied to the account immediately. Remember to follow a naming convention for your account and OU names.

resource "aws_organizations_organizational_unit" "workload" {
  name      = "workload"
  parent_id = aws_organizations_organization.this.roots[0].id
}


resource "aws_organizations_organizational_unit" "dev" {
  name      = "dev"
  parent_id = aws_organizations_organizational_unit.workload.id

  depends_on = [
    aws_organizations_organizational_unit.workload
  ]
}

resource "aws_organizations_account" "dev" {
  # A friendly name for the member account
  name  = "example-dev"
  email = "validemail@domain.com"

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

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

  parent_id = aws_organizations_organizational_unit.dev.id
}

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. If your organization has enabled AWS SSO then you can use those credentials to switch roles to the new account after you add the account for your users/groups.

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. (You don’t have to use Terragrunt at all for this to work, it’s just one way to manage Terraform code at scale. If you want to learn how to setup your Terraform structure without Terragrunt, take a look at this post.) Management/root is my only account/environment in this project.

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

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!