Merge pull request #78 from tekdj7/main

Customizations for AWS Control Tower (CFCT) Setup solution, Getting Started with SRA, Logging/Stage Script updates
aws-samples · Jan 8, 2022 · 71e46f5 · 71e46f5
2 parents 76dea19 + 501768e
commit 71e46f5
Show file tree

Hide file tree

Showing 31 changed files with 1,671 additions and 548 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -3,6 +3,7 @@
 ## Table of Contents<!-- omit in toc -->
 
 - [Introduction](#introduction)
+- [2022-01-07](#2022-01-07)
 - [2021-12-16](#2021-12-16)
 - [2021-12-10](#2021-12-10)
 - [2021-11-22](#2021-11-22)
@@ -19,11 +20,31 @@ All notable changes to this project will be documented in this file.
 
 ---
 
+## 2022-01-07
+
+### Added<!-- omit in toc -->
+
+- [Customizations for AWS Control Tower (CFCT) Setup](aws_sra_examples/solutions/common/common_cfct_setup) solution
+
+### Changed<!-- omit in toc -->
+
+- Updates to the [stage_solution.sh](https://github.com/aws-samples/aws-security-reference-architecture-examples/blob/main/aws_sra_examples/utils/packaging_scripts/stage_solution.sh) packaging script to support better error logging and include
+  packaging of `common` solutions.
+- In [Common Prerequisites](aws_sra_examples/solutions/common/common_prerequisites) and [AWS Config Management Account](aws_sra_examples/solutions/config/config_management_account) solutions:
+  - Updates to logging to include tracebacks for when exceptions are raised.
+- In [Common Prerequisites](aws_sra_examples/solutions/common/common_prerequisites) solution:
+  - Set `DeletionPolicy=Retain` and `UpdateReplacePolicy=Retain` for the IAM Role: `AWSControlTowerExecution`
+- Renamed `DEPLOYMENT-METHODS.md` to [CFCT-DEPLOYMENT-INSTRUCTIONS.md](aws_sra_examples/docs/CFCT-DEPLOYMENT-INSTRUCTIONS.md) to provide manual and automated steps for deployment of Customizations for Control Tower (CFCT), including prerequisites.
+
+### Removed<!-- omit in toc -->
+
+- CFCT deployment option for the [Common Prerequisites](aws_sra_examples/solutions/common/common_prerequisites) solution.
+
 ## 2021-12-16
 
 ### Added<!-- omit in toc -->
 
-- [Config Management Account](aws_sra_examples/config/config_management_account) solution
+- [Config Management Account](aws_sra_examples/solutions/config/config_management_account) solution
 
 ### Changed<!-- omit in toc -->
 
@@ -40,7 +61,7 @@ All notable changes to this project will be documented in this file.
 ### Added<!-- omit in toc -->
 
 - [Common Prerequisites](aws_sra_examples/solutions/common/common_prerequisites) solution
-- [Deployment Methods](aws_sra_examples/docs/DEPLOYMENT-METHODS.md) documentation
+- `Deployment Methods` documentation
 - [Staging Script](aws_sra_examples/utils/packaging_scripts/) - `stage_solution.sh`
 
 ### Changed<!-- omit in toc -->

diff --git a/README.md b/README.md
@@ -5,31 +5,42 @@ Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. SPDX-License-
 ## Table of Contents<!-- omit in toc -->
 
 - [Introduction](#introduction)
+- [Getting Started with SRA](#getting-started-with-sra)
 - [Example Solutions](#example-solutions)
 - [Utils](#utils)
+- [Environment Setup](#environment-setup)
 - [Repository and Solution Naming Convention](#repository-and-solution-naming-convention)
 - [Frequently Asked Questions](#frequently-asked-questions)
 - [Contributors](#contributors)
 - [License Summary](#license-summary)
 
 ## Introduction
 
-This repository contains AWS CloudFormation templates to help developers and engineers deploy AWS security-related services in a multi-account environment following patterns that align with the
-[AWS Security Reference Architecture](https://docs.aws.amazon.com/prescriptive-guidance/latest/security-reference-architecture/). The Amazon Web Services (AWS) Security Reference Architecture (AWS SRA) is a holistic set of guidelines for deploying
-the full complement of AWS security services in a multi-account environment.
+This repository contains code to help developers and engineers deploy AWS security-related services in an `AWS Control Tower` multi-account environment following patterns that align with the
+[AWS Security Reference Architecture](https://docs.aws.amazon.com/prescriptive-guidance/latest/security-reference-architecture/). The Amazon Web Services (AWS) Security Reference Architecture (AWS SRA) is a holistic set of guidelines for deploying the full complement of AWS security services in a multi-account environment.
 
-The AWS service configurations and resources (e.g. IAM roles and policies) deployed by these templates are deliberately very restrictive. They are intended to illustrate an implementation path rather than provide a complete solution. You will need to
-modify and tailor these templates to suit your individual environment and security needs.
+The AWS service configurations and resources (e.g. IAM roles and policies) deployed by these templates are deliberately very restrictive. They are intended to illustrate an implementation pattern rather than provide a complete solution. You may need to modify and tailor these solutions to suit your environment and security needs.
 
-The examples within this repository have been deployed and tested using the corresponding deployment platform (e.g. AWS Control Tower and AWS CloudFormation StackSets).
+The examples within this repository have been deployed and tested within an `AWS Control Tower` environment using `AWS CloudFormation` as well as the `Customizations for AWS Control Tower (CfCT)` solution.
+
+## Getting Started with SRA
+
+![How to get started process diagram](./aws_sra_examples/docs/artifacts/where-to-start-process.png)
+
+1. Setup the environment to configure [AWS Control Tower](https://docs.aws.amazon.com/controltower/latest/userguide/getting-started-with-control-tower.html) within a new or existing AWS account.
+2. Deploy the [Common Prerequisites](aws_sra_examples/solutions/common/common_prerequisites) solution.
+3. Choose a deployment method:
+   - [AWS CloudFormation StackSets/Stacks](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/what-is-cfnstacksets.html)
+   - [Customizations for AWS Control Tower (CFCT)](https://aws.amazon.com/solutions/implementations/customizations-for-aws-control-tower/)
+4. (Optional) - Deploy the [Customizations for AWS Control Tower (CFCT) Setup](aws_sra_examples/common/common_cfct_setup) solution. **Note** Only implement if the CFCT deployment method was selected.
+5. Per your requirements select one or all of the [Example Solutions](aws_sra_examples/solutions) to implement via the selected deployment method.
 
 ## Example Solutions
 
-- CloudTrail
-  - [Organization CloudTrail](aws_sra_examples/solutions/cloudtrail/cloudtrail_org)
 - Common
-  - [Common Prerequisites](aws_sra_examples/solutions/common/common_prerequisites)
   - [Common Register Delegated Administrator](aws_sra_examples/solutions/common/common_register_delegated_administrator)
+- CloudTrail
+  - [Organization CloudTrail](aws_sra_examples/solutions/cloudtrail/cloudtrail_org)
 - Config
   - [Config Management Account](aws_sra_examples/solutions/config/config_management_account)
   - [Organization Aggregator](aws_sra_examples/solutions/config/config_aggregator_org)
@@ -56,6 +67,13 @@ The examples within this repository have been deployed and tested using the corr
 - packaging_scripts
   - package-lambda.sh (Creates the Lambda zip file and uploads to an S3 bucket)
 
+## Environment Setup
+
+Based on the deployment method selected these solutions are required to implement SRA solutions.
+
+- [Common Customizations for AWS Control Tower (CFCT) Setup](aws_sra_examples/common/common_cfct_setup)
+- [Common Prerequisites](aws_sra_examples/solutions/common/common_prerequisites)
+
 ## Repository and Solution Naming Convention
 
 The repository is organized by AWS service solutions, which include deployment platforms (e.g., AWS Control Tower and AWS CloudFormation StackSet).

diff --git a/aws_sra_examples/docs/DEPLOYMENT-METHODS.md → ...ples/docs/CFCT-DEPLOYMENT-INSTRUCTIONS.md b/aws_sra_examples/docs/DEPLOYMENT-METHODS.md → ...ples/docs/CFCT-DEPLOYMENT-INSTRUCTIONS.md
@@ -1,27 +1,41 @@
-# Deployment Methods<!-- omit in toc -->
+# Customizations for AWS Control Tower Deployment Instructions<!-- omit in toc -->
 
 Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. SPDX-License-Identifier: CC-BY-SA-4.0
 
 ---
 
 ## Table of Contents<!-- omit in toc -->
 
-- [Customizations for AWS Control Tower Deployment Instructions](#customizations-for-aws-control-tower-deployment-instructions)
+- [Prerequisites](#prerequisites)
 - [References](#references)
 
-## Customizations for AWS Control Tower Deployment Instructions
+## Prerequisites
 
-### Prerequisites<!-- omit in toc -->
+### Enable Trusted Access for AWS CloudFormation StackSets<!-- omit in toc -->
+
+1. Within the AWS CloudFormation StackSets console page, `Enable trusted access` with AWS Organizations to use service-managed permissions.
+2. See [Enable trusted access with AWS Organizations](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/stacksets-orgs-enable-trusted-access.html) for more details.
+3. To verify that the trusted access is enabled:
+   1. Within the AWS Organizations console page, select `Services` from the side menu
+   2. Verify that `CloudFormation StackSets` has `Trusted access = Access enabled`
+
+### Create the AWSControlTowerExecution IAM Role<!-- omit in toc -->
+
+- The `AWSControlTowerExecution` Role provides the support needed to deploy solutions to the `management account` across regions as CloudFormation `StackSets` and it is required for the SRA CFCT solution deployments.
+- This role is created as part of the [common_prerequisites](../solutions/common/common_prerequisites) solution deployment.
+
+## Deploy Customizations for AWS Control Tower (CFCT)<!-- omit in toc -->
+
+The below prerequisites can be accomplished via the [common_cfct_setup](../solutions/common/common_cfct_setup/) automated solution or they can be done manually following the below steps.
 
 1. Move the `Organizations Management Account` to an Organizational Unit (OU) (e.g. Management), so that CloudFormation StackSets can be deployed to the `Management Account`
    1. Within the AWS Control Tower console page, select `Organizational units` from the side menu, click the `Add an OU` button, and set the `OU name = Management`
    2. Within the AWS Organizations console page, select `AWS accounts` from the side menu
       1. Select the checkbox next to the `Management Account`
       2. From the `Actions` menu, select `Move` and select the new `Management OU` that was created above
       3. Select `Move AWS account`
-2. Within the AWS CloudFormation StackSets console page, `Enable trusted access` with AWS Organizations to use service-managed permissions. To verify that the trusted access is enabled:
-   1. Within the AWS Organizations console page, select `Services` from the side menu
-   2. Verify that `CloudFormation StackSets` has `Trusted access = Access enabled`
+2. Create the `AWSControlTowerExecution` IAM role in the `management account (home region)` by launching an AWS CloudFormation **Stack** using the
+   [sra-common-prerequisites-control-tower-execution-role.yaml](../solutions/common/common_prerequisites/templates/sra-common-prerequisites-control-tower-execution-role.yaml) template file as the source.
 3. Deploy the [Customizations for AWS Control Tower](https://aws.amazon.com/solutions/implementations/customizations-for-aws-control-tower/) solution following the below instructions.
    1. In the `Management account (home region)`, deploy a new CloudFormation stack with the below recommended settings:
       <!-- markdownlint-disable-next-line MD034 -->
@@ -30,48 +44,49 @@ Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. SPDX-License-
       - `AWS CodePipeline Source` = AWS CodeCommit
       - `Failure Tolerance Percentage` = 0
       - Acknowledge that AWS CloudFormation might create IAM resources with custom names
-   2. On the local machine install [git](https://git-scm.com/downloads) and [git-remote-codecommit](https://docs.aws.amazon.com/codecommit/latest/userguide/how-to-connect.html).
-   3. Clone the AWS CodeCommit repository via `git clone codecommit::<HOME REGION>://custom-control-tower-configuration custom-control-tower-configuration`
+
+### AWS CodeCommit Repo<!-- omit in toc -->
+
+1. On the local machine install [git](https://git-scm.com/downloads) and [git-remote-codecommit](https://docs.aws.amazon.com/codecommit/latest/userguide/how-to-connect.html).
+2. Clone the AWS CodeCommit repository via `git clone codecommit::<HOME REGION>://custom-control-tower-configuration custom-control-tower-configuration`
 
 ### Deployment Instructions<!-- omit in toc -->
 
 1. Determine which version of the [Customizations for AWS Control Tower](https://aws.amazon.com/solutions/implementations/customizations-for-aws-control-tower/) solution you have deployed:
-   1. Within the `management account (home region)` find the **CloudFormation Stack** for the Customizations for Control Tower (e.g. custom-control-tower-initiation)
+   1. Within the `management account (home region)` find the **CloudFormation Stack** for the Customizations for Control Tower (e.g. `custom-control-tower-initiation`, `sra-common-cfct-setup-main-ssm-rCFCTStack`, `sra-common-cfct-setup-main-rCFCTStack`)
    2. Select the `Outputs` tab
    3. The `CustomControlTowerSolutionVersion` **Value** is the version running in the environment
       1. Version 1 = v1.x.x = manifest.yaml version 2020-01-01
       2. Version 2 = v2.x.x = manifest.yaml version 2021-03-15
-2. Create the `AWSControlTowerExecution` IAM role in the `management account (home region)` by launching an AWS CloudFormation **Stack** using the
-   [sra-common-prerequisites-control-tower-execution-role.yaml](../solutions/common/common_prerequisites/templates/sra-common-prerequisites-control-tower-execution-role.yaml) template file as the source.
-3. Follow the instructions for the cooresponding version:
+2. Follow the instructions for the cooresponding version:
    - [Version 1 Deployment Instructions](#version-1-deployment-instructions)
    - [Version 2 Deployment Instructions](#version-2-deployment-instructions)
 
 #### Version 1 Deployment Instructions<!-- omit in toc -->
 
 1. Copy the files to the Customizations for AWS Control Tower configuration `custom-control-tower-configuration`
-     - parameters [**required for manifest version 2020-01-01**]
-       - Copy the parameter files from the `parameters` folder
-       - Only one of the main parameter files is required. We recommend using the `main-ssm` file.
-     - policies [optional]
-       - service control policies files (\*.json)
-     - templates [**required**]
-       - Copy the template files from the `templates` folder that are referenced in the `manifest.yaml`
-       - Only one of the main template files is required. We recommend using the `main-ssm` file.
-     - `manifest.yaml` [**required**]
+   - parameters [**required for manifest version 2020-01-01**]
+     - Copy the parameter files from the `parameters` folder
+     - Only one of the main parameter files is required. We recommend using the `main-ssm` file.
+   - policies [optional]
+     - service control policies files (\*.json)
+   - templates [**required**]
+     - Copy the template files from the `templates` folder that are referenced in the `manifest.yaml`
+     - Only one of the main template files is required. We recommend using the `main-ssm` file.
+   - `manifest.yaml` [**required**]
 2. Verify and update the parameters within each of the parameter json files to match the target environment
 3. Update the manifest.yaml file with the `organizational unit names`, `account names` and `SSM parameters` for the target environment
 4. Deploy the Customizations for AWS Control Tower configuration by pushing the code to the `AWS CodeCommit` repository or uploading to the `AWS S3 Bucket`
 
 #### Version 2 Deployment Instructions<!-- omit in toc -->
 
 1. Copy the files to the Customizations for AWS Control Tower configuration `custom-control-tower-configuration`
-     - policies [optional]
-       - service control policies files (\*.json)
-     - templates [**required**]
-       - Copy the template files from the `templates` folder that are referenced in the `manifest-v2.yaml`
-       - Only one of the main template files is required. We recommend using the `main-ssm` file.
-     - `manifest-v2.yaml` [**required**]
+   - policies [optional]
+     - service control policies files (\*.json)
+   - templates [**required**]
+     - Copy the template files from the `templates` folder that are referenced in the `manifest-v2.yaml`
+     - Only one of the main template files is required. We recommend using the `main-ssm` file.
+   - `manifest-v2.yaml` [**required**]
 2. Rename the `manifest-v2.yaml` to `manifest.yaml`
 3. Update the manifest.yaml file with the `parameters`, `organizational unit names`, `account names` and `SSM parameters` for the target environment
 4. Deploy the Customizations for AWS Control Tower configuration by pushing the code to the `AWS CodeCommit` repository or uploading to the `AWS S3 Bucket`

diff --git a/aws_sra_examples/docs/artifacts/where-to-start-process.png b/aws_sra_examples/docs/artifacts/where-to-start-process.png
diff --git a/aws_sra_examples/docs/artifacts/where-to-start-process.pptx b/aws_sra_examples/docs/artifacts/where-to-start-process.pptx