AWS Organization Formation is an Infrastructure as Code (IaC) tool for AWS Organizations.
AWS Organization Formation (also: org-formation
) has 3 main features:
- Infrastructure as Code for AWS Organizations:
Organization resources reference | Example organization file | CLI Reference
- CloudFormation annotations to provision resources cross account:
Annotated CloudFormation reference | Examples | CLI Reference
- Automation of account creation and resource provisioning:
Automation task file reference | Example tasks file | CLI Reference
Want more? here a list of 50+ features 😎😎😎
With npm installed, run
> npm install -g aws-organization-formation
You can now execute the commandline program org-formation
. try:
> org-formation --help
To get started you first need an org-formation
template that describes all your Organization resources such as Accounts, OUs and SCPs.
After Installation you can generate this file using the following command:
> org-formation init organization.yml --region us-east-1 [--profile org-master-account]
example output organization.yml file
AWSTemplateFormatVersion: '2010-09-09-OC'
Organization:
Root:
Type: OC::ORG::MasterAccount
Properties:
AccountName: My Organization Root
AccountId: '123123123123'
Tags:
budget-alarm-threshold: '2500'
account-owner-email: [email protected]
OrganizationRoot:
Type: OC::ORG::OrganizationRoot
Properties:
ServiceControlPolicies:
- !Ref RestrictUnusedRegionsSCP
ProductionAccount:
Type: OC::ORG::Account
Properties:
RootEmail: [email protected]
AccountName: Production Account
Tags:
budget-alarm-threshold: '2500'
account-owner-email: [email protected]
DevelopmentAccount:
Type: OC::ORG::Account
Properties:
RootEmail: [email protected]
AccountName: Development Account
Tags:
budget-alarm-threshold: '2500'
account-owner-email: [email protected]
DevelopmentOU:
Type: OC::ORG::OrganizationalUnit
Properties:
OrganizationalUnitName: development
Accounts:
- !Ref DevelopmentAccount
ProductionOU:
Type: OC::ORG::OrganizationalUnit
Properties:
OrganizationalUnitName: production
Accounts:
- !Ref ProductionAccount
RestrictUnusedRegionsSCP:
Type: OC::ORG::ServiceControlPolicy
Properties:
PolicyName: RestrictUnusedRegions
Description: Restrict Unused regions
PolicyDocument:
Version: '2012-10-17'
Statement:
- Sid: DenyUnsupportedRegions
Effect: Deny
NotAction:
- 'cloudfront:*'
- 'iam:*'
- 'route53:*'
- 'support:*'
Resource: '*'
Condition:
StringNotEquals:
'aws:RequestedRegion':
- eu-west-1
- us-east-1
- eu-central-1
Note: If you prefer to set up CI/CD run org-formation init-pipeline
instead. It will create a CodeCommit repository and CodePipeline that will update your organization upon every commit!
You can make changes to the file you generated and upate your organization using the update
commmand. Alternatively you can run create-change-set
and update-change-set
. Read more in the cli reference
Once you got the hang of managing organization resources, use these organization resources to write smarter cloudformation that allows you to provision resources across your organization. Read more about managing resources across accounts.
Just like with the resources within your AWS Account, managing AWS Organization resources as code allows you to apply changes automatically, reducing manual work, inconsistencies and mistakes.
If you are considering to use an account vending machine (e.g. AWS Control Tower) to create and manage new accounts within your organization: Do realize that the account vending machine allows you to quickly create organization resources but only has limited facilities when it comes to updating and maintaining these resources.
What happens when I remove an account from the organization.yml?
If you remove an account from the organization it will not be deleted. Deleting accounts using api calls is not supported by AWS.
After running update
the account that is removed from the organization will be not be able to be part of organization bindings.
\> org-formation update ./examples/organization.yml --profile org-formation
OC::ORG::Account | Development4Account | Forget
OC::ORG::OrganizationalUnit | DevelopmentOU | Detach Account (Development4Account)
OC::ORG::OrganizationalUnit | DevelopmentOU | CommitHash
After running update-stacks
any stack that was deployed to this account using org-formation will be deleted from the target account. Stacks that have been created by other means will not be affected.
Obviously: having a task file will do both update
and update-stacks
in the right sequence and you're done!
If you removed and account and want to re-add it:
Just add it back to the organization.yml. Make sure you run update
and update-stacks
(or perform-tasks
) and your account will particapate in all bindings and the stacks will be re-deployed to the account.
As long as the account was not deleted in full org-formation
will identify it by the RootEmail
(or AccountId
) attribute in the organization.yml
What happens when I rename an account (AccountName attribute) in org-formation?
Renaming accounts is not possible using API's. You will have to log into the account as root to change the account name in AWS.
If you change the AccountName attribute in org-formation this will warn you about the above and will, when resolving references to the account, use the account name from the organization.yml file.
What happens when I rename an account (logical name) in org-formation?
The logical name, just like with CloudFormation is how you refer to the account from within your templates. The logical account is also used as an identifier within org-formation.
If you rename an account, by its logical name, org-formation will first notice that the resource by the old logical name has gone and forget
it. Later it will discover the new same account by its new logical name and match it with the physical account that already exists in AWS. It will match the two thus completing the rename.
Why is nesting OU's or a custom OrganizationAccessRole not supported?
No reason other than not bumping into this usecase so far.
Really happy to implement this based on someone else's usecase.