Skip to content

Reference Architecture: Terraform AWS Organizations account baseline

User guide

Pre-requisites

You'll need an email to create and register your AWS Organization Root Account. For this purpose we recommend to avoid using a personal email account. Instead, whenever possible, it should ideally be associated, with a distribution list email such as a GSuite Group to ensure the proper admins member's team (DevOps | SecOps | Cloud Engineering Team) to manage its notifications avoiding a single point of contact (constraint).

Email setup example

GSuite Group Email address: aws@domain.com (to which admins / owners belong), and then using the + we generate the aliases automatically implicitly when running Terraform's Leverage code.

  • 📧 aws+security@binbash.com.ar
  • 📧 aws+shared@binbash.com.ar
  • 📧 aws+network@binbash.com.ar
  • 📧 aws+apps-devstg@binbash.com.ar
  • 📧 aws+apps-prd@binbash.com.ar

Reference Code as example

#
# Project Prd: services and resources related to production are placed and
#  maintained here.
#
resource "aws_organizations_account" "apps_prd" {
  name      = "apps-prd"
  email     = "aws+apps-prd@doamin.ar"
  parent_id = aws_organizations_organizational_unit.apps_prd.id
}

Reference AWS Organization init workflow

Steps for initial AWS Organization setup

  1. Create a brand new AWS Account, intended to be our AWS Organization Management (root) Account

  2. Via AWS Web Console: in project_name-management previously created account (eg, name: leverage-management, email: aws@binbash.com.ar) create the mgmt-org-admin IAM user with Admin privileges (admin IAM policy attached), which will be use for the initial AWS Org bootstrapping.

    • 📒 NOTE: After it’s 1st execution only nominated Org admin users will persist in the project-management account.
  3. Via AWS Web Console: in project-management account create mgmt-org-admin IAM user AWS ACCESS KEYS

    • 📒 NOTE: This could be created all in one in the previous step (Nº 2).

    leverage-org

    Figure: AWS Web Console screenshot. (Source: Binbash, "AWs Organization management account init IAM admin user", accessed June 16th 2021).

    leverage-org

    Figure: AWS Web Console screenshot. (Source: Binbash, "AWs Organization management account init IAM admin user", accessed June 16th 2021).

  4. Set your IAM credentials in the machine your're going to exec the leverage cli (remember this are the mgmt-org-admin temporary user credentials shown in the screenshot immediately above).

  5. Set up your Leverage reference architecture configs in order to work with your new account and `org-mgmt-admin IAM user

  6. Setup and create the terraform remote state for the new AWS Org Management account

  7. The AWS Organization from the Reference Architecture /le-tf-infra-aws/root/global/organizations will be orchestrated using the leverage cli following the standard workflow.

    • 📒 the Management account has to be imported into de the code.
  8. Verify your Management account email address in order to invite existing (legacy) AWS accounts to join your organization.

Organization setup post-steps

AWS Organization setup post-steps

  1. Following the doc orchestrate vía the leverage cli workflow the Mgmt Account IAM layer (base-identities) with the admin IAM Users (consider this/these users will have admin privileges over the entire AWS Org assuming the OrganizationAccountAccessRole) -> le-tf-infra-aws/root/global/base-identities

    • 📒 The IAM role: OrganizationAccessAccountRole => does not exist in the initial Management (root) account, this will be created by the code in this layer.
  2. Mgmt account admin user permanent credentials set up => setup in your workstation the AWS credentials) for the OrganizationAccountAccessRole IAM role (project_short-root-oaar, eg: bb-root-oaar). Then validate within each initial mgmt account layer that the profile bb-root-oaar is correctly configured at the below presented config files, as well as any other necessary setup.

  3. Setup (code and config files) and Orchestrate the /security/global/base-identities layer via leverage cli on your security account for consolidated and centralized User Mgmt and access to the AWS Org.

  4. AWS Organizations: invite pre-existing (legacy) accounts

  5. 📒 Pending to document the debug mode for the mfa script