How to create an AWS Organization for your Account with the AWS CDK
Tags: aws, cdk, projen, management
Published: 2022-11-03 21:22:12

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](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.custom_resources-readme.html) 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](https://github.com/projen/projen) and [cdk-organizations](https://github.com/pepperize/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](https://portal.aws.amazon.com/billing/signup#/start)
1. Prepare an IAM User with `AdministratorAccess`: [Create admin group](https://docs.aws.amazon.com/IAM/latest/UserGuide/getting-started_create-admin-group.html)
1. Create and save your `AccessKey`: [Create access key](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html#Using_CreateAccessKey)
1. Configure the AWS CLI: [Configuration basics](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html#cli-configure-quickstart-creds)

## Create the project

- Create a new CDK TypeScript App project

```shell
mkdir my-organization
cd my-organization
npx projen new awscdk-app-ts --projenrc-ts=true
```
- Add [cdk-organizations](https://github.com/pepperize/cdk-organizations) to your dependencies in `.projenrc.ts`

```typescript
const project = new awscdk.AwsCdkTypeScriptApp({
  //...
  deps: ["@pepperize/cdk-organizations"],
});
```
- Install the new dependency
```shell
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`

```typescript
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

```typescript
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

```typescript
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: "your-email+first-member@example.com",
});
```

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.

```typescript
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: "your-email+first-member@example.com",
});

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

```typescript
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: "your-email+first-member@example.com",
});

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

const production = new Account(stack, "Production", {
  accountName: "production",
  email: "your-email+production@example.com",
  parent: ou,
});
const sandbox = new Account(stack, "Sandbox", {
  accountName: "sandbox",
  email: "your-email+sandbox@example.com",
  parent: ou,
});
```

## What's next

- [Enable an AWS Service for trusted access](https://github.com/pepperize/cdk-organizations#enable-an-aws-service-trusted-service)
- [Delegate an AWS Service for an registered admin account](https://github.com/pepperize/cdk-organizations#delegated-administrator)
- [Enable policy types](https://github.com/pepperize/cdk-organizations#enable-a-policy-type)
- [Create a policy](https://github.com/pepperize/cdk-organizations#policy)
- [Tag your AWS Organization resources](https://github.com/pepperize/cdk-organizations#tagging-resources)

References:
- [Usage - CDK Organizations](https://github.com/pepperize/cdk-organizations#usage)
- [API Reference - CDK Organizations](https://github.com/pepperize/cdk-organizations/blob/main/API.md)
- [User Guide - AWS Organizations](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_introduction.html)
- [Example - CDK Organizations](https://github.com/pepperize/cdk-organizations-example)