pepperize.cdk-organizations 0.0.64

This project provides a CDK construct managing AWS organizations, organizational units and accounts.

AWS Organizations

This project provides a CDK construct managing AWS organizations, organizational units and accounts.

Currently, there is no @aws-cdk/aws-organizations available. See this Issue on AWS CDK.

• AWS Account Management Reference Guide
• AWS Organizations User Guide
• AWS API Reference
• AWS CDK Custom Resources

API Reference

See API.md

Install

TypeScript

npm install @pepperize/cdk-organizations

or

yarn add @pepperize/cdk-organizations

Python

pip install pepperize.cdk-organizations

C# / .Net

dotnet add package Pepperize.CDK.Organizations

Getting Started

1. Prepare an IAM User with AdministratorAccess

   To deploy your new organization, you have to create an Administrator with an Access Key

   • Creating your first IAM admin user and user group
   • Managing access keys for IAM users

2. Create a new CDK TypeScript App project with projen

   mkdir my-project
   cd my-project
   git init -b main
   npx projen new awscdk-app-ts
   

3. Add @pepperize/cdk-organizations to your dependencies in .projenrc.js

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

4. Create a stack

   export class OrganizationStack extends Stack {
     constructor(scope: Construct, id: string, props: StackProps = {}) {
       super(scope, id, props);
   
       // Create or import your organization
       const organization = new Organization(stack, "Organization", {});
       // Add organizational units, accounts, policies ...
     }
   }
   

Usage

Organization

To create a new organization or import an existing organization, add the following construct to your stack:

const organization = new Organization(stack, "Organization", {
  featureSet: FeatureSet.ALL,
});

• FeatureSet.ALL is required for advanced features like Service Control Policies and is the preferred way to work with AWS Organizations
• The account which deploys the stack automatically becomes the management account of the new organization.
• If an organization already exists, it will be automatically imported. The account which deploys the stacks must be the management account.
• If the construct gets removed from the stack the organization still remains and must be manually deleted.
• For deletion of an organization you must previously remove all the member accounts, OUs, and policies from the organization.
• Currently, you can have only one root. AWS Organizations automatically creates it for you when you create the new organization.
• It can only be used from within the management account in the us-east-1 region.

Organizational Unit (OU)

To create a new organizational unit (OU), add the following construct to your stack:

const organizationUnit = new OrganizationalUnit(stack, "Organization", {
  organizationalUnitName: "Project2",
  parent: organisation.root,
});

To import an existing organizational unit (OU), add the following to your stack:

const organizationUnit = OrganizationalUnit.fromOrganizationalUnitId(stack, "Organization", {
  organizationalUnitId: "ou-1234",
  organizationalUnitName: "Project2",
  parent: organisation.root,
});

• The parent of an organizational unit (OU) can be either the organization's root or another OU within the organization.
• An organizational unit (OU) can't be moved. You have to create a new one and move all the accounts.
• For deletion of an organizational unit (OU) you must first move all accounts out of the OU and any child OUs, and then you can delete the child OUs.
• It can only be used from within the management account in the us-east-1 region.

Account

To create a new account, add the following construct to your stack:

new Account(stack, "Account", {
  accountName: "MyAccount",
  email: "[e-mail]",
  iamUserAccessToBilling: IamUserAccessToBilling.ALLOW,
  parent: organization.root,
});

To import an existing account, add the following to your stack:

Account.fromAccountId(stack, "ImportedAccount", {
  accountId: "123456789012",
  parent: organization.root,
});

• The email address must not already be associated with another AWS account. You may suffix the email address, i.e. [e-mail].
• An account will be created and then moved to the parent, if the parent is an organizational unit (OU).
• It can only be used from within the management account in the us-east-1 region.
• An account can't be deleted easily, if the construct gets removed from the stack the account still remains. Closing an AWS account

Limitations

AWS Organizations has some limitations:

• The stack can only be deployed in the us-east-1 region.
• The stack's account must be the management account of an existing organization.
• The stack's account becomes the management account of the new organization.
• An account belongs only to one organization with a single root.

Contributing

Contributions of all kinds are welcome :rocket: Check out our contributor's guide.

For a quick start, check out a development environment:

git clone [e-mail]:pepperize/cdk-organizations
cd cdk-organizations
 # install dependencies
yarn
# build with projen
yarn build

Example

See example

import { App, Stack } from "aws-cdk-lib/core";
import {
  Account,
  DelegatedAdministrator,
  EnableAwsServiceAccess,
  EnablePolicyType,
  FeatureSet,
  IamUserAccessToBilling,
  Organization,
  OrganizationalUnit,
  Policy,
  PolicyAttachment,
  PolicyType,
} from "@pepperize/cdk-organizations";

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

// Create an organization
const organization = new Organization(stack, "Organization", {
  featureSet: FeatureSet.ALL,
});
// Enable AWS Service Access (requires FeatureSet: ALL)
new EnableAwsServiceAccess(stack, "EnableAwsServiceAccess", {
  servicePrincipal: "service-abbreviation.amazonaws.com",
});

// Create an account
const account = new Account(stack, "SharedAccount", {
  accountName: "SharedAccount",
  email: "[e-mail]",
  roleName: "OrganizationAccountAccessRole",
  iamUserAccessToBilling: IamUserAccessToBilling.ALLOW,
  parent: organization.root,
});
// Enable a delegated admin account
new DelegatedAdministrator(stack, "DelegatedAdministrator", {
  account: account,
  servicePrincipal: "service-abbreviation.amazonaws.com",
});

// Create an OU in the current organizations root
const projects = new OrganizationalUnit(stack, "ProjectsOU", {
  organizationalUnitName: "Projects",
  parent: organization.root,
});
new Account(stack, "Project1Account", {
  accountName: "SharedAccount",
  email: "[e-mail]",
  parent: projects,
});

// Create a nested OU and attach two accounts
const project2 = new OrganizationalUnit(stack, "Project2OU", {
  organizationalUnitName: "Project2",
  parent: projects,
});
new Account(stack, "Project2DevAccount", {
  accountName: "Project 2 Dev",
  email: "[e-mail]",
  parent: project2,
});
new Account(stack, "Project2ProdAccount", {
  accountName: "Project 2 Prod",
  email: "[e-mail]",
  parent: project2,
});

// Enable the service control policy (SCP) type within the organization
new EnablePolicyType(stack, "EnablePolicyType", {
  root: organization.root,
  policyType: PolicyType.SERVICE_CONTROL_POLICY,
});
// Create and attach and Service Control Policy (SCP)
const policy = new Policy(stack, "Policy", {
  content: '{\\"Version\\":\\"2012-10-17\\",\\"Statement\\":{\\"Effect\\":\\"Allow\\",\\"Action\\":\\"s3:*\\"}}',
  description: "Enables admins of attached accounts to delegate all S3 permissions",
  policyName: "AllowAllS3Actions",
  policyType: PolicyType.SERVICE_CONTROL_POLICY,
});
new PolicyAttachment(stack, "PolicyAttachment", {
  target: organization.root,
  policy: policy,
});

Alternatives

• AWS Bootstrap Kit
• Terraform AWS Provider
• AWS Deployment Framework (ADF)
• AWS Organization Formation