This reference architecture and also the steps outlined in this review are still under development and wont work as-is.
Please do
thanks!
This is a reference architecture to get started quickly with using org-formation
as well as provide examples of best practices and demonstrates the capabilities. The reference architecture is built with the following core principles:
To use this reference architecture, follow the Getting Started. If you want to deploy additional stacks using org-formation on top of this reference architecture, then it is advised to do that using delegated builds. Within the org-formation GitHub there will be example stacks configured as delegated builds that are usable, but are not eligeble to be part of the reference architecture because they either depend on an external system (not batteries included) or not always relevent (uses an AWS service that does something that is not always relevant). Examples are:
To create an AWS Organization based on this reference architecture, managed by org-formation follow these steps end to end.
org-formation
org-formation
repositoryHint: if you are using Google as an email provider, you can use team+something@domain.com to create unique addresses that all arrive in the same email box
Create an AWS Account. This will be the management account of your AWS Organization
Parameter | Where to find it | Example |
---|---|---|
{{management-account-id}} | Top right -> your account -> My Account | 341696816352 |
You will use AWS SSO to obtain access to the AWS Accounts after we are done with the initial setup. IAM Users including the root user should not be used as a security best practice for human access.
org-formation
repositoryParameter | Description | Example |
---|---|---|
SSO start URL | Go to AWS SSO -> Settings -> User Portal -> User Portal URL | https://dgega332fa.awsapps.com/start |
{{sso-instance-arn}} | Go to AWS SSO -> Settings -> ARN | arn:aws:sso:::instance/ssoins-6987b39db64e1ecd |
{{sso-admin-group-id}} | Go to AWS SSO -> Groups -> Administrator -> Details -> Group ID | 99672ac0cf-8495fd69-c57e-4214-88a4-b9f41eed0d32 |
{{sso-auditor-group-id}} | Go to AWS SSO -> Groups -> Auditor -> Details -> Group ID | 99672ac0cf-8495fd69-c57e-4214-88a4-b9f41eed0d32 |
{{sso-developer-group-id}} | Go to AWS SSO -> Groups -> Developer -> Details -> Group ID | 99672ac0cf-8495fd69-c57e-4214-88a4-b9f41eed0d32 |
{{sso-supporter-group-id}} | Go to AWS SSO -> Groups -> Supporter -> Details -> Group ID | 99672ac0cf-8495fd69-c57e-4214-88a4-b9f41eed0d32 |
Configuring AWS SSO manually using AWS SSO itself as an identity provider is the quickest and easiest way to get started (and is batteries included). At the time of writing AWS SSO does not support automating this via an API, as soon as it does, this guide will be updated accordingly. If you want to configure an external Identity Provider, then start here.
Parameter | Description | Source | Example |
---|---|---|---|
{{management-account-id}} | 12 digit identifier of the management account | Create the AWS Management Account | 341696816352 |
{{state-bucket-name}} | S3 bucket where the IaC state will be stored | choose | organization-formation-state-341696816352-prd |
{{organization-name}} | Alias of the management account | choose | bee-awesome |
{{primary-aws-region}} | The primary AWS region to deploy to | choose | us-east-1 |
{{management-root-email-address}} | Email address used to register the management account | Create the AWS Management Account | platform.team@bee.awesome |
{{security-root-email-address}} | Email address for the security account | Prerequisites | platform.team+security@bee.awesome |
{{log-archive-root-email-address}} | Email address for the log-archive account | Prerequisites | platform.team+logarchive@bee.awesome |
{{budget-alarm-email-address}} | Email address to receive budget alarms | Prerequisites | platform.team+budget@bee.awesome |
{{orgbuild-root-email-address}} | Email address for the org build account | Prerequisites | platform.team+org-build@bee.awesome |
{{sso-instance-arn}} | AWS SSO instance ARN | Configure AWS SSO | arn:aws:sso:::instance/ssoins-6987b39db64e1ecd |
{{sso-admin-group-id}} | Principal ID from Identity Provider's group used by administrators | Configure AWS SSO | 99672ac0cf-8495fd69-c57e-4214-88a4-b9f41eed0d32 |
{{sso-auditor-group-id}} | Principal ID from Identity Provider's group used by auditors | Configure AWS SSO | 99672ac0cf-8495fd69-c57e-4214-88a4-b9f41eed0d32 |
{{sso-developer-group-id}} | Principal ID from Identity Provider's group used by auditors | Configure AWS SSO | 99672ac0cf-8495fd69-c57e-4214-88a4-b9f41eed0d32 |
{{sso-supporter-group-id}} | Principal ID from Identity Provider's group used by supporters | Configure AWS SSO | 99672ac0cf-8495fd69-c57e-4214-88a4-b9f41eed0d32 |
org-formation
In this step, you run OrgFormation locally using the credentials of the root user of the management account. This is the only time you will use the root user of any account for any purpose and the root user will be closed off as the last step in this guide.
Note: you might need to run the OrgFormation commands more than once.
npm install -g aws-organization-formation
If you already have an existing organization, then the following command generates an organization.yml file for you based on the current structure of your organization.
npx org-formation init organization.yml --region _Primary Region_ --cross-account-role-name OrganizationFormationBuildAccessRole --print-stack --verbose
You can then merge that with the ./src/organization.yml file in the way you like and continue with this guide.
npx org-formation update ./src/organization.yml --verbose
org-formation
uses inside of the Management Account
aws cloudformation create-stack --stack-name org-formation-role --template-body file://src/templates/000-org-build/role.yml --capabilities CAPABILITY_NAMED_IAM
000-org-build
to be used as the initial commit for the OrgBuild CodeCommit repository. From the top level of this repository, execute:
zip ./src/templates/000-org-build/initial-commit src/**/*.* .gitignore .org-formationrc *.yml *.json README.md
000-org-build
. This creates the build roles, state bucket and file and the OrgFormation build pipeline in the OrgBuild account. It also uploads this entire local repository as an initial commit to the Git repository that the build pipeline will then execute.
npx org-formation perform-tasks ./src/templates/000-org-build/_tasks.yml --organization-file ./src/organization.yml --max-concurrent-stacks 50 --max-concurrent-tasks 1 --print-stack --verbose
When you have finished the setup, we will need to delete the S3 bucket containing the state in the management account. This was created in step 2 because at that time the OrgBuild account, was assumed to not exist yet.
org-formation
repositoryHere you will configure command line access to the CodeCommit repository that will trigger the Build Pipeline in the OrgBuild Account. It requires you to configure the aws cli to use SSO and the clone the repository using HTTPS git-remote-codecommit (GRC)
You will need to provide the following details:
Parameter | Description | Example |
---|---|---|
SSO start URL | The landing page URL to be found in the AWS SSO of the management account | https://dgega332fa.awsapps.com/start |
SSO region | The default region | us-east-1 |
SSO account id | Select the OrgBuild account from the drop-down | 222140350420 |
SSO role name | Select a role with write permission the drop-down | Administrator |
CLI default client Region | The default region | us-east-1 |
CLI default output format | Whatever format you prefer | yaml |
CLI profile name | Name of the profile, choose wisely | ba-orgbuild-admin |
Configure support for CodeCommit git-remote-codecommit
Using your IDP (either AWS SSO itself or an external IDP), log into the OrgBuild account, navigate to AWS CodeCommit, find the repository URL and clone
It looks something like this
git clone codecommit::eu-central-1://<AWS_CLI_PROFILE_NAME>@organization-formation