Merge pull request #75 from tekdj7/main

common_prerequisites solution, deployment-methods doc, staging script…
aws-samples · Dec 10, 2021 · cac62c3 · cac62c3
2 parents e1bcfb3 + 31d98ab
commit cac62c3
Show file tree

Hide file tree

Showing 24 changed files with 3,481 additions and 473 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -3,6 +3,7 @@
 ## Table of Contents<!-- omit in toc -->
 
 - [Introduction](#introduction)
+- [2021-12-10](#2021-12-10)
 - [2021-11-22](#2021-11-22)
 - [2021-11-20](#2021-11-20)
 - [2021-11-19](#2021-11-19)
@@ -17,11 +18,27 @@ All notable changes to this project will be documented in this file.
 
 ---
 
+## 2021-12-10
+
+### Added<!-- omit in toc -->
+
+- [Common Prerequisites](aws_sra_examples/solutions/common/common_prerequisites/) solution
+- [Deployment Methods](aws_sra_examples/docs/DEPLOYMENT-METHODS.md) documentation
+- [Staging Script](aws_sra_examples/utils/packaging_scripts/) - `stage_solution.sh`
+
+### Changed<!-- omit in toc -->
+
+- Nothing Changed
+
+### Fixed<!-- omit in toc -->
+
+- Nothing Fixed
+
 ## 2021-11-22
 
 ### Added<!-- omit in toc -->
 
-- EC2 Default EBS Encryption solution
+- [EC2 Default EBS Encryption](aws_sra_examples/solutions/ec2/ec2_default_ebs_encryption) solution
 
 ### Changed<!-- omit in toc -->
 
@@ -31,7 +48,7 @@ All notable changes to this project will be documented in this file.
 
 ### Added<!-- omit in toc -->
 
-- S3 Block Account Public Access solution
+- [S3 Block Account Public Access](aws_sra_examples/solutions/s3/s3_block_account_public_access) solution
 
 ### Changed<!-- omit in toc -->
 
@@ -76,9 +93,9 @@ All notable changes to this project will be documented in this file.
 
 ### Added<!-- omit in toc -->
 
-- AWS IAM Access Analyzer solution
-- Organization AWS Config Aggregator Solution
-- Common Register Delegated Administrator Solution
+- [AWS IAM Access Analyzer](aws_sra_examples/solutions/iam/iam_access_analyzer/) solution
+- [Organization AWS Config Aggregator](aws_sra_examples/solutions/config/config_aggregator_org/) solution
+- [Common Register Delegated Administrator](aws_sra_examples/solutions/common/common_register_delegated_administrator/) solution
 
 ### Changed<!-- omit in toc -->
 

diff --git a/README.md b/README.md
@@ -27,6 +27,9 @@ The examples within this repository have been deployed and tested using the corr
 
 - 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)
 - Config
   - [Organization Aggregator](aws_sra_examples/solutions/config/config_aggregator_org)
   - [Organization Conformance Pack](aws_sra_examples/solutions/config/config_conformance_pack_org)

diff --git a/aws_sra_examples/docs/DEPLOYMENT-METHODS.md b/aws_sra_examples/docs/DEPLOYMENT-METHODS.md
@@ -0,0 +1,90 @@
+# Deployment Methods<!-- 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)
+- [References](#references)
+
+## Customizations for AWS Control Tower Deployment Instructions
+
+### Prerequisites<!-- omit in toc -->
+
+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`
+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 -->
+      - `Amazon S3 URL` = https://s3.amazonaws.com/solutions-reference/customizations-for-aws-control-tower/latest/custom-control-tower-initiation.template
+      - `Stack name` = custom-control-tower-initiation
+      - `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`
+
+### 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)
+   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:
+   - [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
+       - 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
+     - `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`
+
+### Delete Instructions<!-- omit in toc -->
+
+1. Within the Customizations for AWS Control Tower configuration
+   1. Remove the solution configuration from the `manifest.yaml` file
+   2. (Optional) Delete the parameter (Version 1 only) and template files for the solution
+2. Deploy the Customizations for AWS Control Tower configuration
+3. After the pipeline completes, log into the `management account` and navigate to the `CloudFormation StackSet` page
+   1. Delete the Stack Instances from the `CustomControlTower-<solution_name>*` CloudFormation StackSets
+   2. After the Stack Instances are deleted, delete the `CustomControlTower-<solution_name>*` CloudFormation StackSets
+
+## References
+
+- [Customizations for AWS Control Tower](https://aws.amazon.com/solutions/implementations/customizations-for-aws-control-tower/)
diff --git a/aws_sra_examples/solutions/common/common_prerequisites/README.md b/aws_sra_examples/solutions/common/common_prerequisites/README.md
@@ -0,0 +1,157 @@
+# SRA Prerequisites<!-- 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 -->
+
+- [Introduction](#introduction)
+- [Deployed Resource Details](#deployed-resource-details)
+- [Implementation Instructions](#implementation-instructions)
+- [References](#references)
+
+## Introduction
+
+The `SRA Prerequisites Solution` creates the resources (`Staging S3 Buckets` and `Execution IAM Role`) and configuration (`SSM Parameters`) for simplifying the deployment of SRA solutions within an AWS Control Tower environment. All resources that support tags are provided a tag keypair of `sra-solution: sra-common-prerequisites`.
+
+## Deployed Resource Details
+
+![Architecture](./documentation/common-prerequisites.png)
+
+### 1.0 Organization Management Account<!-- omit in toc -->
+
+#### 1.1 AWS CloudFormation<!-- omit in toc -->
+
+- All resources are deployed via AWS CloudFormation as a StackSet and Stack Instance within the management account or a CloudFormation Stack within a specific account.
+- The [Customizations for AWS Control Tower](https://aws.amazon.com/solutions/implementations/customizations-for-aws-control-tower/) solution deploys all templates as a CloudFormation `StackSet`.
+- For parameter details, review the AWS [CloudFormation templates](templates/).
+
+#### 1.2 Org ID AWS Lambda IAM Role<!-- omit in toc -->
+
+- The AWS Org ID Lambda IAM Role allows the AWS Lambda service to assume the role and perform actions defined in the attached IAM policies.
+
+#### 1.3 Org ID AWS Lambda Function<!-- omit in toc -->
+
+- An external deployment package is used in the AWS Lambda Function in the [sra-common-prerequisites-staging-s3-bucket.yaml](templates/sra-common-prerequisites-staging-s3-bucket.yaml) that contains the logic to determine the AWS Organization ID
+- The function is triggered by CloudFormation Create, Update, and Delete events.
+
+#### 1.4 AWS Lambda CloudWatch Log Group<!-- omit in toc -->
+
+- `AWS Lambda Function` logs are sent to a CloudWatch Log Group `</aws/lambda/<LambdaFunctionName>` to help with debugging and traceability of the actions performed.
+- By default the `AWS Lambda Function` will create the CloudWatch Log Group with a `Retention` (Never expire) and the logs are encrypted with a CloudWatch Logs service managed encryption key.
+- Optional parameters are included to allow creating the CloudWatch Log Group, which allows setting `KMS Encryption` using a customer managed KMS key and setting the `Retention` to a specific value (e.g. 14 days).
+
+#### 1.5 AWS SSM Parameter Store<!-- omit in toc -->
+
+- Configuration parameters are created/updated within the `SSM Parameter Store` on CloudFormation events and the parameters are used to simplify deployment of this solution and future SRA solutions.
+- All parameters are created under the `/sra/` hierarchy path in all regions of the `management account`.
+- Optional parameters are included to create the parameters in all `member accounts` in the same regions that are enabled in the `management account`.
+  - This allows for common SSM parameters to be resolved in the `member accounts` for future SRA solutions, and customer workload solutions.
+- Common parameters created will be retained even if the CloudFormation stacks from this solution are deleted.
+
+#### 1.6 Staging S3 Bucket<!-- omit in toc -->
+
+- The S3 Bucket is used to store solution files (Lambda Zip files, CloudFormation templates, and other deployment files) that will be used for staging.
+- S3 bucket is created in all regions of the `management account` with a name following this syntax: `sra-staging-<aws-account-number>-<aws-region>`.
+- Optional parameters are included to create an S3 bucket in all `member accounts` in the same regions that are enabled in the `management account` with a name following this syntax: `sra-staging-<aws-account-number>-<aws-region>`.
+  - This allows for a staging S3 bucket to be used in the `member accounts` for future SRA solutions, and customer workload solutions.
+
+#### 1.7 Parameter AWS Lambda IAM Role<!-- omit in toc -->
+
+- The AWS Lambda Function Role allows the AWS Lambda service to assume the role and perform actions defined in the attached IAM policies.
+
+#### 1.8 Parameter AWS Lambda Function<!-- omit in toc -->
+
+- An inline AWS Lambda Function in the [sra-common-prerequisites-management-account-parameters.yaml](templates/sra-common-prerequisites-management-account-parameters.yaml) contains the logic for discovering common values in your Control Tower landing
+  zone. (e.g., Root Organizational Unit ID, Control Tower Home Region, Audit Account ID)
+- The function is triggered by CloudFormation Create, Update, and Delete events.
+
+#### 1.9 AWS Lambda CloudWatch Log Group<!-- omit in toc -->
+
+- See [1.4 AWS Lambda CloudWatch Log Group](#14-aws-lambda-cloudwatch-log-group)
+
+#### 1.10 AWS Control Tower Execution Role<!-- omit in toc -->
+
+- The `AWSControlTowerExecution` Role provides the support needed to deploy solutions to the `management account` across regions as CloudFormation `StackSets`.
+
+#### 1.11 AWS SSM Parameter Store<!-- omit in toc -->
+
+- See [1.5 AWS SSM Parameter Store](#15-aws-ssm-parameter-store)
+
+#### 1.12 Staging S3 Bucket<!-- omit in toc -->
+
+- See [1.6 Staging S3 Bucket](#16-staging-s3-bucket)
+
+### All Existing and Future Organization Member Accounts<!-- omit in toc -->
+
+#### 2.1 AWS CloudFormation<!-- omit in toc -->
+
+- See [1.1 AWS CloudFormation](#11-aws-cloudformation)
+
+#### 2.2 AWS SSM Parameter Store<!-- omit in toc -->
+
+- See [1.5 AWS SSM Parameter Store](#15-aws-ssm-parameter-store)
+
+#### 2.3 Staging S3 Bucket<!-- omit in toc -->
+
+- See [1.6 Staging S3 Bucket](#16-staging-s3-bucket)
+
+## Implementation Instructions
+
+### Prerequisites<!-- omit in toc -->
+
+- AWS Control Tower is deployed.
+- `aws-security-reference-architecture-examples` repository is stored on your local machine or pipeline where you will be deploying from.
+- **Note:** If the parameter `Create SRA Staging S3 Bucket in Member Accounts = true`, make sure the following elective AWS Control Tower guardrails are disabled for all OUs:
+  - Disallow Changes to Encryption Configuration for Amazon S3 Buckets
+  - Disallow Changes to Logging Configuration for Amazon S3 Buckets
+  - Disallow Changes to Bucket Policy for Amazon S3 Buckets
+  - Disallow Changes to Lifecycle Configuration for Amazon S3 Buckets
+
+### Solution Deployment<!-- omit in toc -->
+
+1. In the `management account (home region)`, launch the AWS CloudFormation **Stack** using the [sra-common-prerequisites-staging-s3-bucket.yaml](templates/sra-common-prerequisites-staging-s3-bucket.yaml) template file as the source.
+2. Package the solution, see the [Staging](#staging) instructions.
+3. Choose a Deployment Method:
+   - [AWS CloudFormation](#aws-cloudformation)
+   - [Customizations for AWS Control Tower](../../../docs/DEPLOYMENT-METHODS.md#customizations-for-aws-control-tower-deployment-instructions)
+
+#### AWS CloudFormation<!-- omit in toc -->
+
+1. In the `management account (home region)`, launch the AWS CloudFormation **Stack** using the [sra-common-prerequisites-management-account-parameters.yaml](templates/sra-common-prerequisites-management-account-parameters.yaml) template file as the
+   source.
+2. In the `management account (home region)`, launch the AWS CloudFormation **Stack** using the template file as the source from the below chosen options:
+   - **Option 1:** (Recommended) Use this template, [sra-common-prerequisites-main-ssm.yaml](templates/sra-common-prerequisites-main-ssm.yaml), for a more automated approach where CloudFormation parameters resolve SSM parameters.
+   - **Option 2:** Use this template, [sra-common-prerequisites-main.yaml](templates/sra-common-prerequisites-main.yaml), where input is required for the CloudFormation parameters, without resolving SSM parameters.
+
+### Staging<!-- omit in toc -->
+
+1. Package the Lambda code into a zip file and upload the solution files (Lambda Zip files, CloudFormation templates, and other deployment files) to the SRA Staging S3 bucket (from above step), using the
+   [Packaging script](../../../utils/packaging_scripts/stage_solution.sh).
+
+   - `SRA_REPO` environment variable should point to the folder where `aws-security-reference-architecture-examples` repository is stored.
+   - `BUCKET` environment variable should point to the S3 Bucket where the solution files are stored.
+   - See CloudFormation Output from Step 1 in the [Solution Deployment](#solution-deployment) instructions. Or follow this syntax: `sra-staging-<CONTROL-TOWER-MANAGEMENT-ACCOUNT>-<CONTROL-TOWER-HOME-REGION>`
+
+     ```bash
+     # Example (assumes repository was downloaded to your home directory)
+     export SRA_REPO="$HOME"/aws-security-reference-architecture-examples/aws_sra_examples
+     export BUCKET=sra-staging-123456789012-us-east-1
+     sh "$SRA_REPO"/utils/packaging_scripts/stage_solution.sh \
+         --staging_bucket_name $BUCKET \
+         --solution_directory "$SRA_REPO"/solutions/common/common_prerequisites
+     ```
+
+     ```bash
+     # Use template below and set the 'SRA_REPO' and 'SRA_BUCKET' with your values.
+     export SRA_REPO=
+     export BUCKET=
+     sh "$SRA_REPO"/utils/packaging_scripts/stage_solution.sh \
+         --staging_bucket_name $BUCKET \
+         --solution_directory "$SRA_REPO"/solutions/common/common_prerequisites
+     ```
+
+## References
+
+- [How AWS Control Tower works with roles to create and manage accounts](https://docs.aws.amazon.com/controltower/latest/userguide/roles-how.html)
+- [AWS Systems Manager Parameter Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html)
+- [Working with AWS CloudFormation StackSets](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/what-is-cfnstacksets.html)
diff --git a/...ions/common/common_prerequisites/customizations_for_aws_control_tower/README.md b/...ions/common/common_prerequisites/customizations_for_aws_control_tower/README.md
@@ -0,0 +1,7 @@
+# Customizations for AWS Control Tower<!-- omit in toc -->
+
+Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. SPDX-License-Identifier: CC-BY-SA-4.0
+
+---
+
+[Customizations for AWS Control Tower Deployment Instructions](../../../docs/DEPLOYMENT-METHODS.md#customizations-for-aws-control-tower-deployment-instructions)