How to create an AWS Organization for your Account with the AWS CDK

With AWS Organizations you are able to create and manage multiple AWS Accounts. With it, you can separate environments, consolidate billing, enable policies for AWS services, backup and tagging. You can organize your AWS Accounts in Organizational Unit to compose a hierarchical structure.

At the time of writing there are different solutions out there to help you to manage your AWS Organization. AWS CloudFormation is missing and there is no support in the AWS CDK. Luckily the AWS CDK Custom Resources module exists, with which it's a charm to create custom AWS CloudFormation Resources based on the AWS Organizations API.

I will give you step-by-step instructions to create your very first AWS Organization with the AWS CDK and the help of projen and cdk-organizations. You only need already an AWS Account created which is not a member or management account of another AWS Organization.

Preparation

1. Use an existing account or create a new account: Signup
2. Prepare an IAM User with AdministratorAccess: Create admin group
3. Create and save your AccessKey: Create access key
4. Configure the AWS CLI: Configuration basics

Create the project

• Create a new CDK TypeScript App project

mkdir my-organization
cd my-organization
npx projen new awscdk-app-ts --projenrc-ts=true

• Add cdk-organizations to your dependencies in .projenrc.ts

const project = new awscdk.AwsCdkTypeScriptApp({
  //...
  deps: ["@pepperize/cdk-organizations"],
});

• Install the new dependency

npx projen

Turn your AWS Account into an AWS Organization

For the simplicity of this step-by-step guide we programmatically add the resources in your src/main.ts. You may refactor it later on.

• Add a new stack to your src/main.ts

import { App, Stack } from "aws-cdk-lib";

const app = new App();
const stack = new Stack();

• Create the AWS organization

Add the Organization construct to your stack

import { Organization } from "@pepperize/cdk-organizations";
import { App, Stack } from "aws-cdk-lib";

const app = new App();
const stack = new Stack();

const organization = Organization(stack, "Organization");

Your AWS Account becomes the management account of the newly created AWS Organization. By default, all features of the organization are enabled, which you need later on to attach policies to your accounts. The Organization construct also handles the sequential account creation.

Create your first member account

import { Account, Organization } from "@pepperize/cdk-organizations";
import { App, Stack } from "aws-cdk-lib";

const app = new App();
const stack = new Stack();

const organization = new Organization(stack, "Organization");
const account = new Account(stack, "FirstMember", {
  accountName: "first-member",
  email: "[e-mail]",
});

This account will automatically be a member of your organization and a direct child of the organizations root.

The email of an account has to be unique across all accounts in AWS.

Create your first organizational unit

With organizational units you can group your accounts into a tree structure. You can also attach policies to organizational units that apply to all accounts in the hierarchy down.

import { Account, Organization, OrganizationalUnit } from "@pepperize/cdk-organizations";
import { App, Stack } from "aws-cdk-lib";

const app = new App();
const stack = new Stack();

const organization = new Organization(stack, "Organization");
const account = new Account(stack, "FirstMember", {
  accountName: "first-member",
  email: "[e-mail]",
});

const ou = new OrganizationalUnit(stack, "Team1", {
  organizationalUnitName: "team-1",
  parent: organization.root,
});

The parent of an organizational unit is either the root of the organization or another organizational unit.

Add your stage accounts

import { Account, Organization, OrganizationalUnit } from "@pepperize/cdk-organizations";
import { App, Stack } from "aws-cdk-lib";

const app = new App();
const stack = new Stack();

const organization = new Organization(stack, "Organization");
const account = new Account(stack, "FirstMember", {
  accountName: "first-member",
  email: "[e-mail]",
});

const ou = new OrganizationalUnit(stack, "Team1", {
  organizationalUnitName: "team-1",
  parent: organization.root,
});

const production = new Account(stack, "Production", {
  accountName: "production",
  email: "[e-mail]",
  parent: ou,
});
const sandbox = new Account(stack, "Sandbox", {
  accountName: "sandbox",
  email: "[e-mail]",
  parent: ou,
});

What's next

• Enable an AWS Service for trusted access
• Delegate an AWS Service for an registered admin account
• Enable policy types
• Create a policy
• Tag your AWS Organization resources

References:

• Usage - CDK Organizations
• API Reference - CDK Organizations
• User Guide - AWS Organizations
• Example - CDK Organizations