Merge pull request #88 from aws-samples/enhancement/documentation-updates

Documentation and instruction updates

Author: andywick-aws

CHANGELOG.md

@@ -3,6 +3,7 @@
 ## Table of Contents<!-- omit in toc -->
 
 - [Introduction](#introduction)
+- [2022-03-29](#2022-03-29)
 - [2022-03-16](#2022-03-16)
 - [2022-03-14](#2022-03-14)
 - [2022-01-07](#2022-01-07)
@@ -22,6 +23,22 @@ All notable changes to this project will be documented in this file.
 
 ---
 
+## 2022-03-29
+
+### Changed<!-- omit in toc -->
+
+- Updated the [Common Prerequisites](aws_sra_examples/solutions/common/common_prerequisites) solution README to remove deploying the Staging S3 Bucket within the Solution Deployment steps. The
+  [DOWNLOAD-AND-STAGE-SOLUTIONS.md](aws_sra_examples/docs/DOWNLOAD-AND-STAGE-SOLUTIONS.md) document now includes this step.
+- Updated the [DOWNLOAD-AND-STAGE-SOLUTIONS.md](aws_sra_examples/docs/DOWNLOAD-AND-STAGE-SOLUTIONS.md) document to include deploying the Staging S3 Bucket template. Also, added an AWS CLI command for deploying the template via the command line.
+- Updated the `Solution Deployment` instructions in all solution README files to include AWS CLI commands for deploying the main templates. The AWS CLI command can be used to deploy the template via the command line within tools like CloudShell.
+- Updated all main template parameters that allow a blank string to include a default empty string allowing the AWS CLI command to work without passing the `optional` parameters.
+- Added an allowed pattern for email address parameters.
+- All solution template description were updated.
+
+### Removed<!-- omit in toc -->
+
+- Removed the sra-common-cfct-setup-main-ssm.yaml template as it was the same as the other main template.
+
 ## 2022-03-16
 
 ### Fixed<!-- omit in toc -->

aws_sra_examples/docs/DOWNLOAD-AND-STAGE-SOLUTIONS.md

@@ -8,8 +8,21 @@ Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. SPDX-License-
 
 1. [Install the prerequisites](#install-the-prerequisites).
 2. [Download the SRA examples code from GitHub](#download-the-sra-examples-code-from-github).
-3. [Authenticate to the AWS management account](#authenticate-to-the-aws-management-account).
-4. Package and stage all the AWS SRA example solutions. For more information see [Staging script details](#staging-script-details).
+
+   ```bash
+   git clone https://github.com/aws-samples/aws-security-reference-architecture-examples.git $HOME/aws-sra-examples
+   cd $HOME/aws-sra-examples
+   ```
+
+3. In the `management account (home region)`, launch an AWS CloudFormation **Stack** using the [sra-common-prerequisites-staging-s3-bucket.yaml](../solutions/common/common_prerequisites/templates/sra-common-prerequisites-staging-s3-bucket.yaml)
+   template file as the source.
+
+   ```bash
+   aws cloudformation deploy --template-file $HOME/aws-sra-examples/aws_sra_examples/solutions/common/common_prerequisites/templates/sra-common-prerequisites-staging-s3-bucket.yaml --stack-name sra-common-prerequisites-staging-s3-bucket --capabilities CAPABILITY_NAMED_IAM
+   ```
+
+4. [Authenticate to the AWS management account](#authenticate-to-the-aws-management-account).
+5. Package and stage all the AWS SRA example solutions. For more information see [Staging script details](#staging-script-details).
    <!-- markdownlint-disable-next-line MD031 -->
 
    ```bash

aws_sra_examples/solutions/cloudtrail/cloudtrail_org/README.md

@@ -148,8 +148,17 @@ In the `management account (home region)`, launch an AWS CloudFormation **Stack*
 
 - **Option 1:** (Recommended) Use the [sra-cloudtrail-org-main-ssm.yaml](templates/sra-cloudtrail-org-main-ssm.yaml) template. This is a more automated approach where some of the CloudFormation parameters are populated from SSM parameters created by
   the [SRA Prerequisites Solution](../../common/common_prerequisites/).
+
+  ```bash
+  aws cloudformation deploy --template-file $HOME/aws-sra-examples/aws_sra_examples/solutions/cloudtrail/cloudtrail_org/templates/sra-cloudtrail-org-main-ssm.yaml --stack-name sra-cloudtrail-org-main-ssm --capabilities CAPABILITY_NAMED_IAM
+  ```
+
 - **Option 2:** Use the [sra-cloudtrail-org-main.yaml](templates/sra-cloudtrail-org-main.yaml) template. Input is required for the CloudFormation parameters where the default is not set.
 
+  ```bash
+  aws cloudformation deploy --template-file $HOME/aws-sra-examples/aws_sra_examples/solutions/cloudtrail/cloudtrail_org/templates/sra-cloudtrail-org-main.yaml --stack-name sra-cloudtrail-org-main --capabilities CAPABILITY_NAMED_IAM --parameter-overrides pAuditAccountId=<AUDIT_ACCOUNT_ID> pLogArchiveAccountId=<LOG_ARCHIVE_ACCOUNT_ID> pOrganizationId=<ORGANIZATION_ID> pSRAStagingS3BucketName=<SRA_STAGING_S3_BUCKET_NAME>
+  ```
+
 #### Verify Solution Deployment<!-- omit in toc -->
 
 1. Log into the `management account` and navigate to the CloudTrail page

aws_sra_examples/solutions/cloudtrail/cloudtrail_org/templates/sra-cloudtrail-org-bucket.yaml

@@ -5,7 +5,7 @@
 AWSTemplateFormatVersion: 2010-09-09
 Description:
   This template enables and configures an AWS S3 bucket for the CloudTrail Organization trail in the Control Tower Log Archive account. -
-  'cloudtrail_org' solution in the repo, https://github.com/aws-samples/aws-security-reference-architecture-examples
+  'cloudtrail_org' solution in the repo, https://github.com/aws-samples/aws-security-reference-architecture-examples (sra-1ssgnse0i)
 
 Metadata:
   SRA:

aws_sra_examples/solutions/cloudtrail/cloudtrail_org/templates/sra-cloudtrail-org-kms.yaml

@@ -5,7 +5,7 @@
 AWSTemplateFormatVersion: 2010-09-09
 Description:
   This template enables and configures an AWS KMS Key for the CloudTrail Organization trail in the Control Tower Audit account. - 'cloudtrail_org'
-  solution in the repo, https://github.com/aws-samples/aws-security-reference-architecture-examples
+  solution in the repo, https://github.com/aws-samples/aws-security-reference-architecture-examples (sra-1ssgnse0i)
 
 Metadata:
   SRA:

aws_sra_examples/solutions/cloudtrail/cloudtrail_org/templates/sra-cloudtrail-org-main-ssm.yaml

@@ -6,7 +6,7 @@ AWSTemplateFormatVersion: 2010-09-09
 Description:
   This template enables an AWS Organizations CloudTrail in the Control Tower Management account with a customer managed KMS key created in the Audit
   account sending the encrypted logs to an S3 bucket created within the Log Archive account. - 'cloudtrail_org' solution in the repo,
-  https://github.com/aws-samples/aws-security-reference-architecture-examples
+  https://github.com/aws-samples/aws-security-reference-architecture-examples (sra-1ssgnse0i)
 
 Metadata:
   SRA:
@@ -111,6 +111,7 @@ Parameters:
   pCloudTrailLogGroupKmsKey:
     AllowedPattern: ^$|^arn:(aws[a-zA-Z-]*){1}:kms:[a-z0-9-]+:\d{12}:key\/[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$
     ConstraintDescription: 'Key ARN example:  arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'
+    Default: ''
     Description:
       (Optional) KMS Key ARN to use for encrypting the CloudTrail log group data. If empty, encryption is enabled with CloudWatch Logs managing the
       server-side encryption keys.
@@ -161,6 +162,7 @@ Parameters:
   pLambdaLogGroupKmsKey:
     AllowedPattern: ^$|^arn:(aws[a-zA-Z-]*){1}:kms:[a-z0-9-]+:\d{12}:key\/[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$
     ConstraintDescription: 'Key ARN example:  arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'
+    Default: ''
     Description:
       (Optional) KMS Key ARN to use for encrypting the Lambda logs data. If empty, encryption is enabled with CloudWatch Logs managing the server-side
       encryption keys.

aws_sra_examples/solutions/cloudtrail/cloudtrail_org/templates/sra-cloudtrail-org-main.yaml

@@ -6,7 +6,7 @@ AWSTemplateFormatVersion: 2010-09-09
 Description:
   This template enables an AWS Organizations CloudTrail in the Control Tower Management account with a customer managed KMS key created in the Audit
   account sending the encrypted logs to an S3 bucket created within the Log Archive account. - 'cloudtrail_org' solution in the repo,
-  https://github.com/aws-samples/aws-security-reference-architecture-examples
+  https://github.com/aws-samples/aws-security-reference-architecture-examples (sra-1ssgnse0i)
 
 Metadata:
   SRA:
@@ -107,6 +107,7 @@ Parameters:
   pCloudTrailLogGroupKmsKey:
     AllowedPattern: ^$|^arn:(aws[a-zA-Z-]*){1}:kms:[a-z0-9-]+:\d{12}:key\/[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$
     ConstraintDescription: 'Key ARN example:  arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'
+    Default: ''
     Description:
       (Optional) KMS Key ARN to use for encrypting the CloudTrail log group data. If empty, encryption is enabled with CloudWatch Logs managing the
       server-side encryption keys.
@@ -148,6 +149,7 @@ Parameters:
   pLambdaLogGroupKmsKey:
     AllowedPattern: ^$|^arn:(aws[a-zA-Z-]*){1}:kms:[a-z0-9-]+:\d{12}:key\/[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$
     ConstraintDescription: 'Key ARN example:  arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'
+    Default: ''
     Description:
       (Optional) KMS Key ARN to use for encrypting the Lambda logs data. If empty, encryption is enabled with CloudWatch Logs managing the server-side
       encryption keys.

aws_sra_examples/solutions/cloudtrail/cloudtrail_org/templates/sra-cloudtrail-org.yaml

@@ -5,7 +5,7 @@
 AWSTemplateFormatVersion: 2010-09-09
 Description:
   This template enables and configures an AWS CloudTrail Organization trail in the Control Tower Management account. - 'cloudtrail_org' solution in
-  the repo, https://github.com/aws-samples/aws-security-reference-architecture-examples
+  the repo, https://github.com/aws-samples/aws-security-reference-architecture-examples (sra-1ssgnse0i)
 
 Metadata:
   SRA:

aws_sra_examples/solutions/common/common_cfct_setup/README.md

@@ -11,11 +11,15 @@ Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. SPDX-License-
 
 ## Introduction
 
-The `SRA Customizations for Control Tower (CFCT) Solution` deploys the [Customizations for AWS Control Tower](https://aws.amazon.com/solutions/implementations/customizations-for-aws-control-tower/) (CFCT) solution. This provides a method to simplify the deployment of SRA solutions and customer customizations within an AWS Control Tower environment.
+The `SRA Customizations for Control Tower (CFCT) Solution` deploys the [Customizations for AWS Control Tower](https://aws.amazon.com/solutions/implementations/customizations-for-aws-control-tower/) (CFCT) solution. This provides a method to simplify
+the deployment of SRA solutions and customer customizations within an AWS Control Tower environment.
 
-The Customizations for AWS Control Tower solution combines AWS Control Tower and other highly-available, trusted AWS services to help customers more quickly set up a secure, multi-account AWS environment using AWS best practices. Before deploying this solution, you must have an AWS Control Tower landing zone deployed in your account.
+The Customizations for AWS Control Tower solution combines AWS Control Tower and other highly-available, trusted AWS services to help customers more quickly set up a secure, multi-account AWS environment using AWS best practices. Before deploying
+this solution, you must have an AWS Control Tower landing zone deployed in your account.
 
-You can easily add customizations to your AWS Control Tower landing zone using an AWS CloudFormation template and service control policies (SCPs). You can deploy the custom template and policies to individual accounts and organizational units (OUs) within your organization. This solution integrates with AWS Control Tower lifecycle events to ensure that resource deployments stay in sync with your landing zone. For example, when a new account is created using the AWS Control Tower account factory, the solution ensures that all resources attached to the account's OUs will be automatically deployed.
+You can easily add customizations to your AWS Control Tower landing zone using an AWS CloudFormation template and service control policies (SCPs). You can deploy the custom template and policies to individual accounts and organizational units (OUs)
+within your organization. This solution integrates with AWS Control Tower lifecycle events to ensure that resource deployments stay in sync with your landing zone. For example, when a new account is created using the AWS Control Tower account
+factory, the solution ensures that all resources attached to the account's OUs will be automatically deployed.
 
 ## Deployed Resource Details
 
@@ -47,9 +51,12 @@ You can easily add customizations to your AWS Control Tower landing zone using a
 
 ### Solution Deployment<!-- omit in toc -->
 
-1. 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-cfct-setup-main-ssm.yaml](templates/sra-common-cfct-setup-main-ssm.yaml), for a more automated approach where CloudFormation parameters resolve SSM parameters.
-   - **Option 2:** Use this template, [sra-common-cfct-setup-main.yaml](templates/sra-common-cfct-setup-main.yaml), where input is required for the CloudFormation parameters, without resolving SSM parameters.
+1. In the `management account (home region)`, launch an AWS CloudFormation **Stack** using the [sra-common-cfct-setup-main.yaml](templates/sra-common-cfct-setup-main.yaml) template file as the source.
+
+   ```bash
+   aws cloudformation deploy --template-file $HOME/aws-sra-examples/aws_sra_examples/solutions/common/common_cfct_setup/templates/sra-common-cfct-setup-main.yaml --stack-name sra-common-cfct-setup-main --capabilities CAPABILITY_NAMED_IAM
+   ```
+
 2. For CodeCommit setup follow these steps: [AWS CodeCommit Repo](../../../docs/CFCT-DEPLOYMENT-INSTRUCTIONS.md#aws-codecommit-repo)
 
 ### Solution Delete Instructions<!-- omit in toc -->