Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/pepperize/cdk-organizations
Manage AWS organizations, organizational units (OU), accounts and service control policies (SCP).
https://github.com/pepperize/cdk-organizations
account account-management aws cdk organizational-units organizations policies tag-resources
Last synced: 22 days ago
JSON representation
Manage AWS organizations, organizational units (OU), accounts and service control policies (SCP).
- Host: GitHub
- URL: https://github.com/pepperize/cdk-organizations
- Owner: pepperize
- License: mit
- Created: 2022-01-10T16:53:57.000Z (almost 3 years ago)
- Default Branch: main
- Last Pushed: 2024-05-23T01:06:53.000Z (7 months ago)
- Last Synced: 2024-05-23T02:48:50.832Z (7 months ago)
- Topics: account, account-management, aws, cdk, organizational-units, organizations, policies, tag-resources
- Language: TypeScript
- Homepage:
- Size: 5.64 MB
- Stars: 158
- Watchers: 6
- Forks: 15
- Open Issues: 23
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
- awesome-cdk - cdk-organizations - CDK constructs that helps to provision AWS Organization, Organizational Units (OU), Accounts and Policies. (Construct Libraries / Multi-accounts setup)
- awesome-cdk - cdk-organizations - CDK constructs that helps to provision AWS Organization, Organizational Units (OU), Accounts and Policies. (Construct Libraries / Multi-accounts setup)
README
[](https://makeapullrequest.com)
[](https://github.com/pepperize/cdk-organizations/blob/main/LICENSE)
[](https://www.npmjs.com/package/@pepperize/cdk-organizations)
[](https://pypi.org/project/pepperize.cdk-organizations/)
[](https://www.nuget.org/packages/Pepperize.CDK.Organizations/)
[](https://s01.oss.sonatype.org/content/repositories/releases/com/pepperize/cdk-organizations/)
[](https://github.com/pepperize/cdk-organizations/actions/workflows/release.yml)
[](https://github.com/pepperize/cdk-organizations/releases)
[](https://gitpod.io/#https://github.com/pepperize/cdk-organizations)
# CDK Organizations [](https://github.com/kolomied/awesome-cdk)
Manage AWS organizations, organizational units (OU), accounts and service control policies (SCP).
Features:
- [Organization](https://github.com/pepperize/cdk-organizations#organization)
- [Organizational Unit (OU)](https://github.com/pepperize/cdk-organizations#organizational-unit-ou)
- [Account](https://github.com/pepperize/cdk-organizations#account)
- [Delegated Administrator](https://github.com/pepperize/cdk-organizations#delegated-administrator)
- [Trusted Service](https://github.com/pepperize/cdk-organizations#enable-an-aws-service-trusted-service)
- [Policies](https://github.com/pepperize/cdk-organizations#policy), [PolicyTypes](https://github.com/pepperize/cdk-organizations#enable-a-policy-type), [PolicyAttachment](https://github.com/pepperize/cdk-organizations#policyattachment)
- [Tagging](https://github.com/pepperize/cdk-organizations#tagging-resources)
[](https://constructs.dev/packages/@pepperize/cdk-organizations)
## Install
### TypeScript
```shell
npm install @pepperize/cdk-organizations
```
or
```shell
yarn add @pepperize/cdk-organizations
```
### Python
```shell
pip install pepperize.cdk-organizations
```
### C\# / .Net
```
dotnet add package Pepperize.CDK.Organizations
```
### Java
```xml
com.pepperize
cdk-organizations
${cdkOrganizations.version}
```
## Contributing
Contributions of all kinds are welcome :rocket: Check out our [contributor's guide](https://github.com/pepperize/cdk-organizations/blob/main/CONTRIBUTING.md).
For a quick start, [check out](https://github.com/pepperize/cdk-organizations/fork) a development environment:
```shell
git clone [email protected]:pepperize/cdk-organizations
cd cdk-organizations
# install dependencies
yarn
# build with projen
yarn build
```
## Getting Started
1. Create a new account
[Signup for AWS](https://portal.aws.amazon.com/billing/signup#/start)
2. Prepare an IAM User with `AdministratorAccess`
To deploy your new organization, you have to create an Administrator with an AccessKey
- [Creating your first IAM admin user and user group](https://docs.aws.amazon.com/IAM/latest/UserGuide/getting-started_create-admin-group.html)
- [Managing access keys for IAM users](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html#Using_CreateAccessKey)
3. Create a new CDK TypeScript App project with [projen](https://github.com/projen/projen)
```shell
mkdir my-project
cd my-project
git init -b main
npx projen new awscdk-app-ts
```
4. Add `@pepperize/cdk-organizations` to your dependencies in `.projenrc.js`
```typescript
const project = new awscdk.AwsCdkTypeScriptApp({
//...
deps: ["@pepperize/cdk-organizations"],
});
```
5. Install the dependency
```shell
npx projen
```
6. Create a stack
```typescript
import { Account, Organization, OrganizationalUnit } from "@pepperize/cdk-organizations";
import { Stack } from "aws-cdk-lib";
export class OrganizationStack extends Stack {
constructor(scope: Construct, id: string, props: StackProps = {}) {
super(scope, id, props);
// Create your organization
const organization = new Organization(stack, "Organization", {});
// Create an organizational unit (OU)
const organizationUnit = new OrganizationalUnit(stack, "OrganizationalUnit", {
organizationalUnitName: "MyFirstOU",
parent: organization.root,
});
// Create an account
const account = new Account(stack, "Account", {
accountName: "MyFirstAccount",
email: "",
parent: organizationUnit,
});
}
}
```
7. Configure your AWS CLI to deploy
- [Configuring the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html)
- [AWSume](https://awsu.me/)
The easiest is to export your access key
```shell
export AWS_ACCESS_KEY_ID=
export AWS_SECRET_ACCESS_KEY=
```
8. Deploy your first AWS organization
```shell
export CDK_DEFAULT_REGION=
export CDK_DEFAULT_ACCOUNT=
```
```shell
yarn deploy
```
## Usage
### Organization
To create a new organization or import an existing organization, add the following construct to your stack:
```typescript
const organization = new Organization(stack, "Organization", {
featureSet: FeatureSet.ALL, // (default) required later on to enable SCPs, enable AWS services or delegate an administrator account
});
organization.root; // The organization's root is automatically created
```
- `FeatureSet.ALL` is required for advanced features like Service Control Policies (SCP) and is the [preferred way to work with AWS Organizations](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_org_support-all-features.html)
- The account which deploys the stack, will automatically become the management account of the new organization.
- If an organization already exists, it will be imported automatically. You can disable this behaviour by passing `importOnDuplicate: false` in the props.
- If the construct is removed from the stack, the organization will remain and must be deleted manually. For deletion of an organization you must previously remove all the member accounts, OUs, and policies from the organization. [Deleting the organization by removing the management account](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_org_delete.html)
- An organization root is automatically created for you when you create the new organization.
See [IOrganization](https://github.com/pepperize/cdk-organizations/blob/main/API.md#@pepperize/cdk-organizations.IOrganization)
### Organization Principal
To retrieve the AWS IAM organization principal in a member account, add the following to any construct:
```
const organization = Organization.of(scope, "Organization");
organization.principal; // The AWS IAM organization principal
```
- This helper construct can be used in any member account in the organization.
See [AWS Organization API Reference - DescribeOrganization](https://docs.aws.amazon.com/organizations/latest/APIReference/API_DescribeOrganization.html)
### Organizational Unit (OU)
To create a new organizational unit (OU), add the following construct to your stack:
```typescript
const organizationUnit = new OrganizationalUnit(stack, "Organization", {
organizationalUnitName: "Project2",
parent: organization.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 OU first, move all the accounts and then delete the old OU.
- 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. [Deleting an organizational unit](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_ous.html#delete-ou)
See [IOrganizationalUnit](https://github.com/pepperize/cdk-organizations/blob/main/API.md#@pepperize/cdk-organizations.IOrganizationalUnit)
#### Organizational Unit (OU) Properties
- `importOnDuplicate` If an organizational unit (OU) with the name exists in the parent, it will be imported.
- `removalPolicy` Default `RemovalPolicy.Retain` If you set `removalPolicy` to `RemovalPolicy.destroy`, the organizational unit (OU) will be deleted on Cloudformation delete event.
See [OrganizationalUnitProps](https://github.com/pepperize/cdk-organizations/blob/main/API.md#@pepperize/cdk-organizations.OrganizationalUnitProps)
### Account
To create a new account, add the following construct to your stack:
```typescript
new Account(stack, "Account", {
accountName: "MyAccount",
email: "[email protected]",
parent: organization.root,
});
```
- The email address must not already be associated with another AWS account. You may suffix the email address, i.e. `[email protected]`.
- The AWS Organizations supports only a one account creation `IN_PROGRESS`. Ensure account creation by using `account2.node.addDependency(account1)` [dependency relationship](https://docs.aws.amazon.com/cdk/api/v1/docs/core-readme.html#dependencies).
- An account will be created and moved to the parent, if the parent is an organizational unit (OU).
- An account can only be created from within the management account.
See [IAccount](https://github.com/pepperize/cdk-organizations/blob/main/API.md#@pepperize/cdk-organizations.IAccount)
#### Account Properties
- `importOnDuplicate` If an account with the same email address exists in the organization, it will be imported.
- `removalPolicy` Default `RemovalPolicy.Retain` If you set `removalPolicy` to `RemovalPolicy.destroy`, the account will be closed. [Closing an AWS account](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_accounts_close.html)
- `iamUserAccessToBilling` Default `IamUserAccessToBilling.ALLOW` If you set `iamUserAccessToBilling` to `ALLOW`, IAM users and roles that have appropriate permissions can view billing information for the account.
- `roleName` Default `OrganizationAccountAccessRole` is preconfigures in the newly created account and grants users in the management account administrator permissions in the new member account.
See [AccountProps](https://github.com/pepperize/cdk-organizations/blob/main/API.md#@pepperize/cdk-organizations.AccountProps)
### Delegated Administrator
A compatible AWS service (trusted service) can register an AWS member account in the organization as an administrator in the organization on your behalf. To enable an AWS account as administrator of that trusted in your organization call `delegateAdministrator` on your account:
```typescript
const account = new Account(stack, "Account", {
accountName: "StackSetsDelegatedAdministrator",
email: "[email protected]",
});
account.delegateAdministrator("stacksets.amazonaws.com");
```
- [AWS services that support Delegated Administrator](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_integrate_services_list.html)
- To be able to use Delegated Administrator, your organization must have [all features](https://github.com/pepperize/cdk-organizations/blob/main/API.md#@pepperize/cdk-organizations.FeatureSet) enabled.
See [DelegatedAdministrator](https://github.com/pepperize/cdk-organizations/blob/main/API.md#@pepperize/cdk-organizations.DelegatedAdministrator)
### Enable an AWS Service (trusted service)
To enable trusted access for a supported AWS service (trusted service), which performs tasks in your organization and its accounts on your behalf, call `enableAwsService` on your organization:
```typescript
const organization = new Organization(stack, "Organization", {
featureSet: FeatureSet.ALL, // (default) the organization must be created with all features enabled
});
organization.enableAwsServiceAccess("ssm.amazonaws.com");
```
- To enable trusted access, you must have [all features](https://github.com/pepperize/cdk-organizations/blob/main/API.md#@pepperize/cdk-organizations.FeatureSet) enabled.
- It's recommended to use only the trusted service's console [How to enable or disable trusted access](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_integrate_services.html#orgs_how-to-enable-disable-trusted-access)
- [AWS services that you can use with AWS Organizations](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_integrate_services_list.html)
See [EnableAwsServiceAccess](https://github.com/pepperize/cdk-organizations/blob/main/API.md#@pepperize/cdk-organizations.EnableAwsServiceAccess)
### Enable a Policy Type
To enable a policy type call `enablePolicyType` on your organization.
```typescript
const organization = new Organization(stack, "Organization", {
featureSet: FeatureSet.ALL, // (default) the organization must be created with all features enabled
});
organization.enablePolicyType(PolicyType.SERVICE_CONTROL_POLICY);
organization.enablePolicyType(PolicyType.TAG_POLICY);
organization.enablePolicyType(PolicyType.BACKUP_POLICY);
organization.enablePolicyType(PolicyType.AISERVICES_OPT_OUT_POLICY);
```
- To create or attach policies later on, you have to [enable all features](https://github.com/pepperize/cdk-organizations/blob/main/API.md#@pepperize/cdk-organizations.FeatureSet) and the [policy type](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies.html#orgs-policy-types) .
See [EnablePolicyType](https://github.com/pepperize/cdk-organizations/blob/main/API.md#enablepolicytype-), [PolicyType](https://github.com/pepperize/cdk-organizations/blob/main/API.md#policytype-).
### Policy
To create a new policy add the following construct to your stack:
```typescript
new Policy(stack, "Policy", {
content: '{\n"Version":"2012-10-17","Statement":{\n"Effect":"Allow","Action":"s3:*"\n}\n}',
description: "Enables admins of attached accounts to delegate all S3 permissions",
policyName: "AllowAllS3Actions",
policyType: PolicyType.SERVICE_CONTROL_POLICY,
});
```
- To create or attach policies, you must have [all features](https://github.com/pepperize/cdk-organizations/blob/main/API.md#@pepperize/cdk-organizations.FeatureSet) and the [policy type](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies.html#orgs-policy-types) enabled.
- The [SCP Syntax](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_scps_syntax.html) is quite similar to IAM policies, but way more limited.
See [Policy](https://github.com/pepperize/cdk-organizations/blob/main/API.md#@pepperize/cdk-organizations.Policy)
### PolicyAttachment
To attach a policy to a root, an organizational unit (OU), or an individual account call `attachPolicy` with the policy to attach:
```typescript
organization.enablePolicyType(PolicyType.TAG_POLICY);
const policy = new Policy(stack, "Policy", {
content: '{\n"tags":{\n"CostCenter":{\n"tag_key":{\n"@@assign":"CostCenter"\n}\n}\n}\n}',
description: "Defines the CostCenter tag key",
policyName: "CostCenterTag",
policyType: PolicyType.TAG_POLICY,
});
organization.attachPolicy(policy);
organizationalUnit.attachPolicy(policy);
account.attachPolicy(policy);
```
- To create or attach policies, you must have [all features](https://github.com/pepperize/cdk-organizations/blob/main/API.md#@pepperize/cdk-organizations.FeatureSet) and the [policy type](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies.html#orgs-policy-types) enabled.
### Tagging resources
To tag a resource you may follow the [AWS CDK Developer Guide - Tagging](https://docs.aws.amazon.com/cdk/v2/guide/tagging.html):
You can add one or more tags to the following resources in AWS Organizations.
- Account
- Organization root
- Organizational unit (OU)
- Policy
See [Tagging AWS Organizations resources](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_tagging.html), [ITaggableResource](https://github.com/pepperize/cdk-organizations/blob/main/API.md#@pepperize/cdk-organizations.ITaggableResource)
#### Tagging an organization's root
```typescript
import { Tags } from "aws-cdk-lib";
const organization = new Organization();
Tags.of(organization.root).add("key", "value");
```
#### Tagging an organizational unit (OU)
```typescript
import { Tags } from "aws-cdk-lib";
const organizationalUnit = new OrganizationalUnit();
Tags.of(organizationalUnit).add("key", "value");
```
#### Tagging an account
```typescript
import { Tags } from "aws-cdk-lib";
const account = new Account();
Tags.of(account).add("key", "value");
```
#### Tagging a policy
```typescript
import { Tags } from "aws-cdk-lib";
const policy = new Policy();
Tags.of(policy).add("key", "value");
```
## Limitations
AWS Organizations has some limitations:
- 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 to only one organization within a single root.
- [Quotas for AWS Organizations](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_reference_limits.html)
> AWS Organizations is a global service with service endpoints in `us-east-1`, `us-gov-west-1` and `cn-northwest-1`. Read also
> [Endpoint to call When using the AWS CLI or the AWS SDK](https://docs.aws.amazon.com/organizations/latest/APIReference/Welcome.html).
> Currently all custom resources of this library are hard set to use `us-east-1`.
## Example
See [example](https://github.com/pepperize/cdk-organizations-example/blob/main/src/example-stack.ts)
```typescript
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)
organization.enableAwsServiceAccess("service-abbreviation.amazonaws.com");
// Create an account
const account1 = new Account(stack, "SharedAccount", {
accountName: "SharedAccount",
email: "[email protected]",
roleName: "OrganizationAccountAccessRole",
iamUserAccessToBilling: IamUserAccessToBilling.ALLOW,
parent: organization.root,
});
// Enable a delegated admin account
account1.delegateAdministrator("service-abbreviation.amazonaws.com");
// Create an OU in the current organizations root
const projects = new OrganizationalUnit(stack, "ProjectsOU", {
organizationalUnitName: "Projects",
parent: organization.root,
});
const account2 = new Account(stack, "Project1Account", {
accountName: "SharedAccount",
email: "[email protected]",
parent: projects,
});
account2.node.addDependency(account1);
// Create a nested OU and attach two accounts
const project2 = new OrganizationalUnit(stack, "Project2OU", {
organizationalUnitName: "Project2",
parent: projects,
});
const account3 = new Account(stack, "Project2DevAccount", {
accountName: "Project 2 Dev",
email: "[email protected]",
parent: project2,
});
account3.node.addDependency(account2);
const account4 = new Account(stack, "Project2ProdAccount", {
accountName: "Project 2 Prod",
email: "[email protected]",
parent: project2,
});
account4.node.addDependency(account3);
// Enable the service control policy (SCP) type within the organization
organization.enablePolicyType(PolicyType.SERVICE_CONTROL_POLICY);
// Create and attach and Service Control Policy (SCP)
const policy = new Policy(stack, "Policy", {
content: '{\n"Version":"2012-10-17","Statement":{\n"Effect":"Allow","Action":"s3:*"\n}\n}',
description: "Enables admins of attached accounts to delegate all S3 permissions",
policyName: "AllowAllS3Actions",
policyType: PolicyType.SERVICE_CONTROL_POLICY,
});
organization.attachPolicy(policy);
// Tagging AWS organization resources of this stack
Tags.of(stack).add("tagKey", "tagValue");
```
## References
- [CDK Organizations API Reference](https://github.com/pepperize/cdk-organizations/blob/main/API.md)
- [AWS Account Management Reference Guide](https://docs.aws.amazon.com/accounts/latest/reference/accounts-welcome.html)
- [AWS Organizations User Guide](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_introduction.html)
- [AWS API Reference](https://docs.aws.amazon.com/organizations/latest/APIReference/Welcome.html)
- [AWS CDK Custom Resources](https://docs.aws.amazon.com/cdk/api/v1/docs/custom-resources-readme.html#custom-resources-for-aws-apis)
## Alternatives
- [AWS Bootstrap Kit](https://github.com/awslabs/aws-bootstrap-kit)
- [Terraform AWS Provider](https://registry.terraform.io/providers/hashicorp/aws/latest)
- [AWS Deployment Framework (ADF)](https://github.com/awslabs/aws-deployment-framework)
- [AWS Organization Formation](https://github.com/org-formation)
- [AWS Control Tower Account Factory for Terraform (ATF)](https://github.com/aws-ia/terraform-aws-control_tower_account_factory)