From 788859df750b706b239bcc6048ba2dc6e5b2d62d Mon Sep 17 00:00:00 2001 From: Andreas Falkenberg Date: Thu, 8 Jun 2023 13:56:17 +0200 Subject: [PATCH 1/4] docs: documentation-enhancements --- docs/admin-guide.md | 7 +++ docs/installation-guide.md | 61 +++++++++++++++---- .../adf-accounts/README.md | 6 ++ 3 files changed, 62 insertions(+), 12 deletions(-) diff --git a/docs/admin-guide.md b/docs/admin-guide.md index a782d5e92..eb2395852 100644 --- a/docs/admin-guide.md +++ b/docs/admin-guide.md @@ -278,6 +278,13 @@ ensures the existence of AWS Accounts defined in `.yml` files within the or alternatively in the bootstrap repository you can find it in the `adf-accounts` directory. +**Note on Provisioning AWS Accounts via AWS ControlTower** +ADF is fully compatible with [AWS ControlTower](https://aws.amazon.com/de/controltower/). +If you deployed ADF and AWS ControlTower in your AWS Organization and if you opted for +vending AWS Accounts via AWS ControlTower, you can ignore the ADF Account Provisioning +feature. Any AWS Account vended via AWS ControlTower will go through the regular ADF +bootstrap process described below. + ### Bootstrapping Accounts #### Bootstrapping Overview diff --git a/docs/installation-guide.md b/docs/installation-guide.md index 71cc89be9..a0f036d12 100644 --- a/docs/installation-guide.md +++ b/docs/installation-guide.md @@ -8,6 +8,20 @@ - [AWS CloudTrail configured](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-create-and-update-a-trail.html) in the `us-east-1` region within the AWS Organizations Management AWS Account. +## ADF-Compability with AWS ControlTower +ADF is fully compatible with [AWS ControlTower](https://aws.amazon.com/de/controltower/). +ADF augments AWS ControlTower. A common operations model is defined as follows: +- AWS ControlTower is responsible for AWS Account creation and OU mapping. +- ADF is responsible for deploying applications as defined in the ADF deployment maps. +In the following, we assume that you install ADF without AWS ControlTower. However, if a specific installation +step requires a "AWS ControlTower-specific actions, we call those out explicitly. + +It is okay to install ADF and AWS ControlTower in different regions. Example: +- Install AWS ControlTower in eu-central-1. +- Install ADF in us-east-1. + +**If you want to use ADF and AWS ControlTower, we recommend that you setup AWS ControlTower prior to installing ADF.** + ## Installation Instructions 1. Ensure you have setup [AWS CloudTrail](https://aws.amazon.com/cloudtrail/) @@ -18,6 +32,7 @@ in the `us-east-1` region within the AWS Organizations Management AWS Account. for AWS Organizations can only be acted upon in the US East (N. Virginia) Region. + 2. In the AWS Console from your management account within `us-east-1`, head over to the Serverless Application Repository *(SAR)*. From there, search for `aws-deployment-framework` *(or "adf")* (ensure the checkbox *"Show apps that @@ -34,6 +49,15 @@ in the `us-east-1` region within the AWS Organizations Management AWS Account. you can specify its Account ID in the parameter `DeploymentAccountId` and leave the`DeploymentAccountName` and `DeploymentAccountEmail` empty. + **AWS ControlTower-specific Note:** + If you use AWS ControlTower, we recommend to create the deployment AWS Account + via the account vending feature of AWS ControlTower. + + It is **MANDATORY**, that your designated deployment AWS Account resides in the + OU `deployment` (case-sensitive!). This can't be changed currently. Otherwise + the ADF deployment will fail! + + Next, specify the `DeploymentAccountMainRegion` parameter as the region that will host your deployment pipelines and would be considered your main AWS region. @@ -44,6 +68,11 @@ in the `us-east-1` region within the AWS Organizations Management AWS Account. Also specify a main notification endpoint *(email)* to receive updates about the bootstrap process. + **AWS ControlTower-specific Note:** + If you use AWS ControlTower, in the `CrossAccountAccessRoleName` section of the + parameters enter the string `AWSControlTowerExecution`. Leave empty otherwise + for a default ADF setup. + When you have entered all required information press **'Deploy'**. 3. As the stack `serverlessrepo-aws-deployment-framework` completes you can now @@ -62,18 +91,26 @@ in the `us-east-1` region within the AWS Organizations Management AWS Account. 4. As part of the AWS CodePipeline Execution from the previous step, the account provisioner component will run *(in CodeBuild)*. - If you let ADF create a new Deployment account for you *(by not giving a - pre-existing account id when deploying from SAR)*, then ADF will handle - creating and moving this account automatically into the deployment OU. - - If you are using a pre-existing deployment account, you will need to move the - account into the deployment OU from within the Organization console, or - add your deployment account into a `.yml` file within the `adf-accounts` - folder *(see docs)*. This action will trigger [AWS Step - Functions](https://aws.amazon.com/step-functions/) to run and start the - bootstrap process for the deployment account. You can view the progress of - this in the AWS Step Functions console from the management account in the - `us-east-1` region. + OPTION 4.1: ONLY applies requsting the creation of a NEW deployment account AND when using ADF for vending AWS Accounts + - If you let ADF create a new Deployment account for you *(by not giving a + pre-existing account id when deploying from SAR)*, then ADF will handle + creating and moving this account automatically into the deployment OU. + + OPTION 4.2: ONLY applies when reusing an pre-created deployment account AND when using ADF for vending AWS Accounts + - If you are using a pre-existing deployment account, you will need to move + the account into the deployment OU from within the Organization console, or + add your deployment account into a `.yml` file within the `adf-accounts` + folder *(see docs)*. + + OPTION 4.3: ONLY applies when reusing an pre-created deployment account AND when using AWS ControlTower for vending AWS Accounts + - Ensure that AWS ControlTower-created deployment AWS Account resides in the + OU `deployment` (case-sensitive!). + + Regardless of the option taken above, after AWS Account cretion, you should see + an [AWS Step Functions](https://aws.amazon.com/step-functions/) run that started + the bootstrap process for the deployment account. You can view the progress of + this in the management account in the AWS Step Functions console for the step + function `AccountBootstrappingStateMachine-` in the `us-east-1` region. 5. Once the Step Function has completed, switch roles over to the newly bootstrapped deployment account in the region you defined as your main region diff --git a/src/lambda_codebase/initial_commit/bootstrap_repository/adf-accounts/README.md b/src/lambda_codebase/initial_commit/bootstrap_repository/adf-accounts/README.md index 5dfb97d87..6fc96daaa 100644 --- a/src/lambda_codebase/initial_commit/bootstrap_repository/adf-accounts/README.md +++ b/src/lambda_codebase/initial_commit/bootstrap_repository/adf-accounts/README.md @@ -7,6 +7,12 @@ Organization. This process enables to end-to-end bootstrapping and associated pipeline generation for new AWS Accounts and is the recommended way to provision and setup AWS Accounts via ADF. +**Note on Provisioning AWS Accounts via AWS ControlTower** +ADF is fully compatible with [AWS ControlTower](https://aws.amazon.com/de/controltower/). +If you deployed ADF and AWS ControlTower in your AWS Organization and if you opted for +vending AWS Accounts via AWS ControlTower, you can ignore the ADF Account Provisioning +feature. + ## Overview When setting ADF for the first time you will have an auto-generated `adf.yml` From 7b2777524177e9c9226a6b39ddd232fd062af611 Mon Sep 17 00:00:00 2001 From: Simon Kok Date: Mon, 24 Jul 2023 14:45:32 +0200 Subject: [PATCH 2/4] Linting and minor code review fixes --- docs/admin-guide.md | 12 +- docs/installation-guide.md | 122 ++++++++++-------- .../adf-accounts/README.md | 10 +- 3 files changed, 80 insertions(+), 64 deletions(-) diff --git a/docs/admin-guide.md b/docs/admin-guide.md index eb2395852..1f8b62c72 100644 --- a/docs/admin-guide.md +++ b/docs/admin-guide.md @@ -278,12 +278,12 @@ ensures the existence of AWS Accounts defined in `.yml` files within the or alternatively in the bootstrap repository you can find it in the `adf-accounts` directory. -**Note on Provisioning AWS Accounts via AWS ControlTower** -ADF is fully compatible with [AWS ControlTower](https://aws.amazon.com/de/controltower/). -If you deployed ADF and AWS ControlTower in your AWS Organization and if you opted for -vending AWS Accounts via AWS ControlTower, you can ignore the ADF Account Provisioning -feature. Any AWS Account vended via AWS ControlTower will go through the regular ADF -bootstrap process described below. +**Note on Provisioning AWS Accounts via AWS Control Tower** +ADF is fully compatible with [AWS Control Tower](https://aws.amazon.com/de/controltower/). +If you deployed ADF and AWS Control Tower in your AWS Organization and if you +opted for vending AWS Accounts via AWS Control Tower, you can ignore the ADF +Account Provisioning feature. Any AWS Account vended via AWS Control Tower will +go through the regular ADF bootstrap process described below. ### Bootstrapping Accounts diff --git a/docs/installation-guide.md b/docs/installation-guide.md index a0f036d12..f74cf37f2 100644 --- a/docs/installation-guide.md +++ b/docs/installation-guide.md @@ -6,21 +6,28 @@ - [git](https://git-scm.com/) - [AWS CodeCommit Setup](https://docs.aws.amazon.com/codecommit/latest/userguide/setting-up-https-unixes.html) - [AWS CloudTrail configured](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-create-and-update-a-trail.html) + in the `us-east-1` region within the AWS Organizations Management AWS Account. -## ADF-Compability with AWS ControlTower -ADF is fully compatible with [AWS ControlTower](https://aws.amazon.com/de/controltower/). -ADF augments AWS ControlTower. A common operations model is defined as follows: -- AWS ControlTower is responsible for AWS Account creation and OU mapping. -- ADF is responsible for deploying applications as defined in the ADF deployment maps. -In the following, we assume that you install ADF without AWS ControlTower. However, if a specific installation -step requires a "AWS ControlTower-specific actions, we call those out explicitly. +## ADF-Compability with AWS Control Tower + +ADF is fully compatible with [AWS Control Tower](https://aws.amazon.com/de/controltower/). +ADF augments AWS Control Tower. A common operations model is defined as follows: + +- AWS Control Tower is responsible for AWS Account creation and OU mapping. +- ADF is responsible for deploying applications as defined in the ADF + deployment maps. -It is okay to install ADF and AWS ControlTower in different regions. Example: -- Install AWS ControlTower in eu-central-1. +In the following, we assume that you install ADF without AWS Control Tower. +However, if a specific installation step requires a "AWS Control Tower-specific +actions, we call those out explicitly. + +It is okay to install ADF and AWS Control Tower in different regions. Example: +- Install AWS Control Tower in eu-central-1. - Install ADF in us-east-1. -**If you want to use ADF and AWS ControlTower, we recommend that you setup AWS ControlTower prior to installing ADF.** +**If you want to use ADF and AWS Control Tower, we recommend that you setup +AWS Control Tower prior to installing ADF.** ## Installation Instructions @@ -33,10 +40,10 @@ It is okay to install ADF and AWS ControlTower in different regions. Example: Region. -2. In the AWS Console from your management account within `us-east-1`, head over - to the Serverless Application Repository *(SAR)*. From there, search for - `aws-deployment-framework` *(or "adf")* (ensure the checkbox *"Show apps that - create custom IAM roles or resource policies"* is checked). +2. In the AWS Console from your management account within `us-east-1`, head + over to the Serverless Application Repository *(SAR)*. From there, search + for `aws-deployment-framework` *(or "adf")* (ensure the checkbox + *"Show apps that create custom IAM roles or resource policies"* is checked). If you are deploying ADF for the first time, fill in the required parameters for your specific use-case. For example, if you have no AWS Organization @@ -45,19 +52,20 @@ It is okay to install ADF and AWS ControlTower in different regions. Example: deployment OU, along with an AWS Account that will be used to house deployment pipelines throughout your Organization. - If you already have an AWS Account you want to use as your deployment account - you can specify its Account ID in the parameter `DeploymentAccountId` - and leave the`DeploymentAccountName` and `DeploymentAccountEmail` empty. + If you already have an AWS Account you want to use as your deployment + account you can specify its Account ID in the parameter + `DeploymentAccountId` and leave the `DeploymentAccountName` plus + `DeploymentAccountEmail` empty. + + **AWS Control Tower-specific Note:** + If you use AWS Control Tower, we recommend to create the deployment AWS + Account via the account vending feature of AWS Control Tower. + + It is **MANDATORY**, that your designated deployment AWS Account resides in + the OU `deployment` (case-sensitive!). This can't be changed currently. + Otherwise, the ADF deployment will fail! - **AWS ControlTower-specific Note:** - If you use AWS ControlTower, we recommend to create the deployment AWS Account - via the account vending feature of AWS ControlTower. - It is **MANDATORY**, that your designated deployment AWS Account resides in the - OU `deployment` (case-sensitive!). This can't be changed currently. Otherwise - the ADF deployment will fail! - - Next, specify the `DeploymentAccountMainRegion` parameter as the region that will host your deployment pipelines and would be considered your main AWS region. @@ -68,10 +76,10 @@ It is okay to install ADF and AWS ControlTower in different regions. Example: Also specify a main notification endpoint *(email)* to receive updates about the bootstrap process. - **AWS ControlTower-specific Note:** - If you use AWS ControlTower, in the `CrossAccountAccessRoleName` section of the - parameters enter the string `AWSControlTowerExecution`. Leave empty otherwise - for a default ADF setup. + **AWS Control Tower-specific Note:** + If you use AWS Control Tower, in the `CrossAccountAccessRoleName` section of + the parameters enter the string `AWSControlTowerExecution`. + Alternatively, leave empty for a default ADF setup. When you have entered all required information press **'Deploy'**. @@ -79,42 +87,50 @@ It is okay to install ADF and AWS ControlTower in different regions. Example: open AWS CodePipeline from within the management account in `us-east-1` and see that there is an initial pipeline execution that has been started. - When ADF is deployed for the first time, it will make the initial commit with - the skeleton structure of the `aws-deployment-framework-bootstrap` CodeCommit - repository. + When ADF is deployed for the first time, it will make the initial commit + with the skeleton structure of the `aws-deployment-framework-bootstrap` + CodeCommit repository. From that initial commit, you can clone the repository to your local environment and make the changes required to define your desired base stacks via AWS CloudFormation Templates, Service Control Policies or Tagging Policies. -4. As part of the AWS CodePipeline Execution from the previous step, the account - provisioner component will run *(in CodeBuild)*. +4. As part of the AWS CodePipeline Execution from the previous step, the + account provisioner component will run *(in CodeBuild)*. + + OPTION 4.1: ONLY applies when requesting the creation of a NEW deployment + account AND when using ADF for vending AWS Accounts. + + - If you let ADF create a new Deployment account for you + *(by not giving a pre-existing account id when deploying from SAR)*, + then ADF will handle creating and moving this account automatically into + the deployment OU. + + OPTION 4.2: ONLY applies when reusing an pre-created deployment account + AND when using ADF for vending AWS Accounts - OPTION 4.1: ONLY applies requsting the creation of a NEW deployment account AND when using ADF for vending AWS Accounts - - If you let ADF create a new Deployment account for you *(by not giving a - pre-existing account id when deploying from SAR)*, then ADF will handle - creating and moving this account automatically into the deployment OU. + - If you are using a pre-existing deployment account, you will need to + move the account into the deployment OU from within the Organization + console, or add your deployment account into a `.yml` file within the + `adf-accounts` folder *(see docs)*. - OPTION 4.2: ONLY applies when reusing an pre-created deployment account AND when using ADF for vending AWS Accounts - - If you are using a pre-existing deployment account, you will need to move - the account into the deployment OU from within the Organization console, or - add your deployment account into a `.yml` file within the `adf-accounts` - folder *(see docs)*. + OPTION 4.3: ONLY applies when reusing an pre-created deployment account + AND when using AWS Control Tower for vending AWS Accounts - OPTION 4.3: ONLY applies when reusing an pre-created deployment account AND when using AWS ControlTower for vending AWS Accounts - - Ensure that AWS ControlTower-created deployment AWS Account resides in the - OU `deployment` (case-sensitive!). + - Ensure that AWS Control Tower-created deployment AWS Account resides in + the OU `deployment` (case-sensitive!). - Regardless of the option taken above, after AWS Account cretion, you should see - an [AWS Step Functions](https://aws.amazon.com/step-functions/) run that started - the bootstrap process for the deployment account. You can view the progress of - this in the management account in the AWS Step Functions console for the step - function `AccountBootstrappingStateMachine-` in the `us-east-1` region. + Regardless of the option taken above, after AWS Account creation, you should + see an [AWS Step Functions](https://aws.amazon.com/step-functions/) run + that started the bootstrap process for the deployment account. You can view + the progress of this in the management account in the AWS Step Functions + console for the step function `AccountBootstrappingStateMachine-` in the + `us-east-1` region. 5. Once the Step Function has completed, switch roles over to the newly - bootstrapped deployment account in the region you defined as your main region - from step 2. + bootstrapped deployment account in the region you defined as your main + region from step 2. An AWS CodeCommit repository will have been created and will contain the initial skeleton structure committed which serves as a starting point for diff --git a/src/lambda_codebase/initial_commit/bootstrap_repository/adf-accounts/README.md b/src/lambda_codebase/initial_commit/bootstrap_repository/adf-accounts/README.md index 6fc96daaa..f195d1757 100644 --- a/src/lambda_codebase/initial_commit/bootstrap_repository/adf-accounts/README.md +++ b/src/lambda_codebase/initial_commit/bootstrap_repository/adf-accounts/README.md @@ -7,11 +7,11 @@ Organization. This process enables to end-to-end bootstrapping and associated pipeline generation for new AWS Accounts and is the recommended way to provision and setup AWS Accounts via ADF. -**Note on Provisioning AWS Accounts via AWS ControlTower** -ADF is fully compatible with [AWS ControlTower](https://aws.amazon.com/de/controltower/). -If you deployed ADF and AWS ControlTower in your AWS Organization and if you opted for -vending AWS Accounts via AWS ControlTower, you can ignore the ADF Account Provisioning -feature. +**Note on Provisioning AWS Accounts via AWS Control Tower** +ADF is fully compatible with [AWS Control Tower](https://aws.amazon.com/de/controltower/). +If you deployed ADF and AWS Control Tower in your AWS Organization and if you +opted for vending AWS Accounts via AWS Control Tower, you can ignore the ADF +Account Provisioning feature. ## Overview From c767c9532f23dc6d73da0a473d8404d77c0c2609 Mon Sep 17 00:00:00 2001 From: Simon Kok Date: Mon, 24 Jul 2023 14:54:03 +0200 Subject: [PATCH 3/4] Apply suggestions from code review --- docs/installation-guide.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/installation-guide.md b/docs/installation-guide.md index f74cf37f2..f32a52064 100644 --- a/docs/installation-guide.md +++ b/docs/installation-guide.md @@ -6,8 +6,7 @@ - [git](https://git-scm.com/) - [AWS CodeCommit Setup](https://docs.aws.amazon.com/codecommit/latest/userguide/setting-up-https-unixes.html) - [AWS CloudTrail configured](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-create-and-update-a-trail.html) - -in the `us-east-1` region within the AWS Organizations Management AWS Account. + in the `us-east-1` region within the AWS Organizations Management AWS Account. ## ADF-Compability with AWS Control Tower @@ -20,9 +19,10 @@ ADF augments AWS Control Tower. A common operations model is defined as follows: In the following, we assume that you install ADF without AWS Control Tower. However, if a specific installation step requires a "AWS Control Tower-specific -actions, we call those out explicitly. +action, we call those out explicitly. It is okay to install ADF and AWS Control Tower in different regions. Example: + - Install AWS Control Tower in eu-central-1. - Install ADF in us-east-1. @@ -115,11 +115,11 @@ AWS Control Tower prior to installing ADF.** console, or add your deployment account into a `.yml` file within the `adf-accounts` folder *(see docs)*. - OPTION 4.3: ONLY applies when reusing an pre-created deployment account + OPTION 4.3: ONLY applies when reusing a pre-existing deployment account AND when using AWS Control Tower for vending AWS Accounts - - Ensure that AWS Control Tower-created deployment AWS Account resides in - the OU `deployment` (case-sensitive!). + - Ensure that the AWS Control Tower-created deployment AWS Account + resides in the OU `deployment` (case-sensitive!). Regardless of the option taken above, after AWS Account creation, you should see an [AWS Step Functions](https://aws.amazon.com/step-functions/) run From 1a98270e3391d98e88f5b833dfaa4be6795aed24 Mon Sep 17 00:00:00 2001 From: Simon Kok Date: Mon, 24 Jul 2023 15:13:04 +0200 Subject: [PATCH 4/4] Apply linting fixes --- docs/installation-guide.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/installation-guide.md b/docs/installation-guide.md index f32a52064..0ae5b640d 100644 --- a/docs/installation-guide.md +++ b/docs/installation-guide.md @@ -39,7 +39,6 @@ AWS Control Tower prior to installing ADF.** for AWS Organizations can only be acted upon in the US East (N. Virginia) Region. - 2. In the AWS Console from your management account within `us-east-1`, head over to the Serverless Application Repository *(SAR)*. From there, search for `aws-deployment-framework` *(or "adf")* (ensure the checkbox @@ -65,7 +64,6 @@ AWS Control Tower prior to installing ADF.** the OU `deployment` (case-sensitive!). This can't be changed currently. Otherwise, the ADF deployment will fail! - Next, specify the `DeploymentAccountMainRegion` parameter as the region that will host your deployment pipelines and would be considered your main AWS region.