This project provides a CDK construct managing AWS organizations, organizational units and accounts.
Project description
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
-
Prepare an IAM User with
AdministratorAccess
To deploy your new organization, you have to create an Administrator with an Access Key
-
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
-
Add
@pepperize/cdk-organizations
to your dependencies in.projenrc.js
const project = new awscdk.AwsCdkTypeScriptApp({ //... deps: ["@pepperize/cdk-organizations"], });
-
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: "info@pepperize.com",
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.
info+account-123456789012@pepperize.com
. - 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 git@github.com: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: "info+shared-account@pepperize.com",
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: "info+project1@pepperize.com",
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: "info+project2-dev@pepperize.com",
parent: project2,
});
new Account(stack, "Project2ProdAccount", {
accountName: "Project 2 Prod",
email: "info+project2-prod@pepperize.com",
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
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for pepperize.cdk-organizations-0.0.64.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 4ca603c875e87d489672fe16e0b435eee5440b19a04345c831ea88a3ac2061e8 |
|
MD5 | f78a6f2ffc060b03d4887e1de8cfb771 |
|
BLAKE2b-256 | 50b35df278b7896b3f7a3523ae6f916e97b615f64a3e2d64fc724db6da89fcf9 |
Hashes for pepperize.cdk_organizations-0.0.64-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 930463191767dfa59680c78972f1503e8bf12495af697bc434d4973fa1d447db |
|
MD5 | 31449a18098ef0e13e11ed456b87d458 |
|
BLAKE2b-256 | d27836134ac1da1bf5416656a25bade6185f6fc34058e7c26adbfcb9c465b419 |