|
| 1 | +# SRA Prerequisites<!-- omit in toc --> |
| 2 | + |
| 3 | +Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. SPDX-License-Identifier: CC-BY-SA-4.0 |
| 4 | + |
| 5 | +## Table of Contents<!-- omit in toc --> |
| 6 | + |
| 7 | +- [Introduction](#introduction) |
| 8 | +- [Deployed Resource Details](#deployed-resource-details) |
| 9 | +- [Implementation Instructions](#implementation-instructions) |
| 10 | +- [References](#references) |
| 11 | + |
| 12 | +## Introduction |
| 13 | + |
| 14 | +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`. |
| 15 | + |
| 16 | +## Deployed Resource Details |
| 17 | + |
| 18 | + |
| 19 | + |
| 20 | +### 1.0 Organization Management Account<!-- omit in toc --> |
| 21 | + |
| 22 | +#### 1.1 AWS CloudFormation<!-- omit in toc --> |
| 23 | + |
| 24 | +- 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. |
| 25 | +- 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`. |
| 26 | +- For parameter details, review the AWS [CloudFormation templates](templates/). |
| 27 | + |
| 28 | +#### 1.2 Org ID AWS Lambda IAM Role<!-- omit in toc --> |
| 29 | + |
| 30 | +- 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. |
| 31 | + |
| 32 | +#### 1.3 Org ID AWS Lambda Function<!-- omit in toc --> |
| 33 | + |
| 34 | +- 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 |
| 35 | +- The function is triggered by CloudFormation Create, Update, and Delete events. |
| 36 | + |
| 37 | +#### 1.4 AWS Lambda CloudWatch Log Group<!-- omit in toc --> |
| 38 | + |
| 39 | +- `AWS Lambda Function` logs are sent to a CloudWatch Log Group `</aws/lambda/<LambdaFunctionName>` to help with debugging and traceability of the actions performed. |
| 40 | +- 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. |
| 41 | +- 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). |
| 42 | + |
| 43 | +#### 1.5 AWS SSM Parameter Store<!-- omit in toc --> |
| 44 | + |
| 45 | +- 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. |
| 46 | +- All parameters are created under the `/sra/` hierarchy path in all regions of the `management account`. |
| 47 | +- Optional parameters are included to create the parameters in all `member accounts` in the same regions that are enabled in the `management account`. |
| 48 | + - This allows for common SSM parameters to be resolved in the `member accounts` for future SRA solutions, and customer workload solutions. |
| 49 | +- Common parameters created will be retained even if the CloudFormation stacks from this solution are deleted. |
| 50 | + |
| 51 | +#### 1.6 Staging S3 Bucket<!-- omit in toc --> |
| 52 | + |
| 53 | +- The S3 Bucket is used to store solution files (Lambda Zip files, CloudFormation templates, and other deployment files) that will be used for staging. |
| 54 | +- S3 bucket is created in all regions of the `management account` with a name following this syntax: `sra-staging-<aws-account-number>-<aws-region>`. |
| 55 | +- 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>`. |
| 56 | + - This allows for a staging S3 bucket to be used in the `member accounts` for future SRA solutions, and customer workload solutions. |
| 57 | + |
| 58 | +#### 1.7 Parameter AWS Lambda IAM Role<!-- omit in toc --> |
| 59 | + |
| 60 | +- The AWS Lambda Function Role allows the AWS Lambda service to assume the role and perform actions defined in the attached IAM policies. |
| 61 | + |
| 62 | +#### 1.8 Parameter AWS Lambda Function<!-- omit in toc --> |
| 63 | + |
| 64 | +- 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 |
| 65 | + zone. (e.g., Root Organizational Unit ID, Control Tower Home Region, Audit Account ID) |
| 66 | +- The function is triggered by CloudFormation Create, Update, and Delete events. |
| 67 | + |
| 68 | +#### 1.9 AWS Lambda CloudWatch Log Group<!-- omit in toc --> |
| 69 | + |
| 70 | +- See [1.4 AWS Lambda CloudWatch Log Group](#14-aws-lambda-cloudwatch-log-group) |
| 71 | + |
| 72 | +#### 1.10 AWS Control Tower Execution Role<!-- omit in toc --> |
| 73 | + |
| 74 | +- The `AWSControlTowerExecution` Role provides the support needed to deploy solutions to the `management account` across regions as CloudFormation `StackSets`. |
| 75 | + |
| 76 | +#### 1.11 AWS SSM Parameter Store<!-- omit in toc --> |
| 77 | + |
| 78 | +- See [1.5 AWS SSM Parameter Store](#15-aws-ssm-parameter-store) |
| 79 | + |
| 80 | +#### 1.12 Staging S3 Bucket<!-- omit in toc --> |
| 81 | + |
| 82 | +- See [1.6 Staging S3 Bucket](#16-staging-s3-bucket) |
| 83 | + |
| 84 | +### All Existing and Future Organization Member Accounts<!-- omit in toc --> |
| 85 | + |
| 86 | +#### 2.1 AWS CloudFormation<!-- omit in toc --> |
| 87 | + |
| 88 | +- See [1.1 AWS CloudFormation](#11-aws-cloudformation) |
| 89 | + |
| 90 | +#### 2.2 AWS SSM Parameter Store<!-- omit in toc --> |
| 91 | + |
| 92 | +- See [1.5 AWS SSM Parameter Store](#15-aws-ssm-parameter-store) |
| 93 | + |
| 94 | +#### 2.3 Staging S3 Bucket<!-- omit in toc --> |
| 95 | + |
| 96 | +- See [1.6 Staging S3 Bucket](#16-staging-s3-bucket) |
| 97 | + |
| 98 | +## Implementation Instructions |
| 99 | + |
| 100 | +### Prerequisites<!-- omit in toc --> |
| 101 | + |
| 102 | +- AWS Control Tower is deployed. |
| 103 | +- `aws-security-reference-architecture-examples` repository is stored on your local machine or pipeline where you will be deploying from. |
| 104 | +- **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: |
| 105 | + - Disallow Changes to Encryption Configuration for Amazon S3 Buckets |
| 106 | + - Disallow Changes to Logging Configuration for Amazon S3 Buckets |
| 107 | + - Disallow Changes to Bucket Policy for Amazon S3 Buckets |
| 108 | + - Disallow Changes to Lifecycle Configuration for Amazon S3 Buckets |
| 109 | + |
| 110 | +### Solution Deployment<!-- omit in toc --> |
| 111 | + |
| 112 | +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. |
| 113 | +2. Package the solution, see the [Staging](#staging) instructions. |
| 114 | +3. Choose a Deployment Method: |
| 115 | + - [AWS CloudFormation](#aws-cloudformation) |
| 116 | + - [Customizations for AWS Control Tower](../../../docs/DEPLOYMENT-METHODS.md#customizations-for-aws-control-tower-deployment-instructions) |
| 117 | + |
| 118 | +#### AWS CloudFormation<!-- omit in toc --> |
| 119 | + |
| 120 | +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 |
| 121 | + source. |
| 122 | +2. In the `management account (home region)`, launch the AWS CloudFormation **Stack** using the template file as the source from the below chosen options: |
| 123 | + - **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. |
| 124 | + - **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. |
| 125 | + |
| 126 | +### Staging<!-- omit in toc --> |
| 127 | + |
| 128 | +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 |
| 129 | + [Packaging script](../../../utils/packaging_scripts/stage_solution.sh). |
| 130 | + |
| 131 | + - `SRA_REPO` environment variable should point to the folder where `aws-security-reference-architecture-examples` repository is stored. |
| 132 | + - `BUCKET` environment variable should point to the S3 Bucket where the solution files are stored. |
| 133 | + - 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>` |
| 134 | + |
| 135 | + ```bash |
| 136 | + # Example (assumes repository was downloaded to your home directory) |
| 137 | + export SRA_REPO="$HOME"/aws-security-reference-architecture-examples/aws_sra_examples |
| 138 | + export BUCKET=sra-staging-123456789012-us-east-1 |
| 139 | + sh "$SRA_REPO"/utils/packaging_scripts/stage_solution.sh \ |
| 140 | + --staging_bucket_name $BUCKET \ |
| 141 | + --solution_directory "$SRA_REPO"/solutions/common/common_prerequisites |
| 142 | + ``` |
| 143 | + |
| 144 | + ```bash |
| 145 | + # Use template below and set the 'SRA_REPO' and 'SRA_BUCKET' with your values. |
| 146 | + export SRA_REPO= |
| 147 | + export BUCKET= |
| 148 | + sh "$SRA_REPO"/utils/packaging_scripts/stage_solution.sh \ |
| 149 | + --staging_bucket_name $BUCKET \ |
| 150 | + --solution_directory "$SRA_REPO"/solutions/common/common_prerequisites |
| 151 | + ``` |
| 152 | + |
| 153 | +## References |
| 154 | + |
| 155 | +- [How AWS Control Tower works with roles to create and manage accounts](https://docs.aws.amazon.com/controltower/latest/userguide/roles-how.html) |
| 156 | +- [AWS Systems Manager Parameter Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html) |
| 157 | +- [Working with AWS CloudFormation StackSets](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/what-is-cfnstacksets.html) |
0 commit comments