ASEA to LZA documentation updates (#1287)

* doc updates

* run tools on Linux

* CloudTrail difference

* notes on sentinel role

* doc to move alb forwarding rule to new table

* add note about enableOptInRegions

Author: oliviergaumond

src/mkdocs/docs/lza-upgrade/comparison/feature-specific-considerations.md

@@ -86,10 +86,21 @@ If you are using ALB IP Forwarding in ASEA, (`"alb-forwarding": true` is set for
           - ca-central-1
 ```
 
-Once the Customizations stage of the pipeline has been successfully run with the configuration file above, a new DynamoDB table will be generated in the `deploymentTargets` account and region specified. This table should be named `Alb-Ip-Forwarding-<VPC_NAME>`. In the same region and account, a DynamoDB table named `
-<ASEA-Prefix>-Alb-Ip-Forwarding-<VPC-ID>` should exist. You will need to copy over all of these entries from the old ALB IP Forwarding table to the new one.
+Once the Customizations stage of the pipeline has been successfully run with the configuration file above, a new DynamoDB table will be generated in the `deploymentTargets` account and region specified. This table should be named `Alb-Ip-Forwarding-<VPC_NAME>`. In the same region and account, a DynamoDB table named `<ASEA-Prefix>-Alb-Ip-Forwarding-<VPC-ID>` should exist. You will need to copy over all of these entries from the old ALB IP Forwarding table to the new one.
 
- For more details about ALB Forwarding in LZA, refer to the [post-deployment instructions of LZA CCCS Medium reference architecture](https://github.com/aws-samples/landing-zone-accelerator-on-aws-for-cccs-medium/blob/main/post-deployment.md#44-configure-application-load-balancer-forwarding).
+For more details about ALB Forwarding in LZA, refer to the [post-deployment instructions of LZA CCCS Medium reference architecture](https://github.com/aws-samples/landing-zone-accelerator-on-aws-for-cccs-medium/blob/main/post-deployment.md#44-configure-application-load-balancer-forwarding).
+
+#### Steps to copy the entries from the old to new Alb-Ip-Forwarding DynamoDB table
+
+To move the ALB forwarding entries from the ASEA table to the LZA table you can use the following procedure for each rule.
+
+1. Retrieve the JSON content from the ASEA table and copy it to a text editor.
+2. Edit the content to remove the `metadata` property. The metadata is added by the automation.
+3. Edit the content to update the `priority` of the rule. You need to select a priority that is not already in use for other rules on the same Application Load Balancer. e.g. If the priority was 10, you can change it to 11, assuming there are no existing rules with priority 11. (Note: this is necessary because both automation are running in parallel at this time)
+4. Add the edited entry to the LZA table.
+5. Wait 1-2 minutes and refresh the content of the table. The metadata property should have been added. In the EC2 console, go to the ALB Listener Rules and confirm a new rule with the new priority was added. This rule should be an exact copy of the previous one.
+6. Once you confirm the new rule was added, you can remove the entry from the ASEA table.
+7. Repeat the process for the other entries until the ASEA table is empty.
 
 ### Managed Active Directory
 !!! note "convert-config warning message"
@@ -337,6 +348,12 @@ If an assume role policy is needed outside of the scope of what's natively suppo
 
 - Create your own CloudFormation template and add it to the `customizations-config.yaml` file, which will be generated in the LZA Configuration CodeCommit repository in the root directory.
 
+#### Microsoft Sentinel Role
+
+If you created a role for Microsoft Sentinel S3 Connector [using the ASEA documentation](https://aws-samples.github.io/aws-secure-environment-accelerator/latest/faq/#how-do-i-create-a-role-for-use-by-azure-sentinel-using-the-new-s3-connector-method), the trust policy format is not supported by LZA and won't be converted properly. Microsoft now recommends to [Create an Open ID Connect (OIDC) web identity provider and an AWS assumed role](https://learn.microsoft.com/en-us/azure/sentinel/connect-aws?tabs=s3#create-an-open-id-connect-oidc-web-identity-provider-and-an-aws-assumed-role) instead of the previous trust policy that trusted an external Microsoft managed AWS account.
+
+We recommend creating a new role (outside ASEA/LZA) based on the latest recommendation and update your Microsoft Sentinel S3 Connector with the new role ARN. Once you confirm the connector work as expected with the new role, you can decommission the previous role that was deployed by ASEA to avoid any issues during the upgrade.
+
 ### Public and Private Hosted Zones
 !!! note "convert-config warning message"
     _The VPC ${vpcItem.name} in account ${accountKey} utilizes a public Route53 zone: ${zone}. Please refer to documentation on how to manage these resources._ or _The VPC ${vpcItem.name} in OU ${ouKey} utilizes a public Route53 zone: ${zone}. Please refer to documentation on how to manage these resources._

src/mkdocs/docs/lza-upgrade/comparison/index.md

@@ -78,6 +78,15 @@ In LZA, the forwarding rule and CloudWatch Log Groups are created in every accou
 ### ELB Access Logs
 LZA creates new S3 buckets to store ELB access logs in every enabled regions in the central logs account (e.g. `asea-elb-access-logs-<account>-<region>`). ASEA stored the ELB access logs on the `asea-logarchive-phase0-aes<region>-<suffix>` bucket. After the upgrade, the `ASEA-LZA-ELB_LOGGING_ENABLED` AWS Config Rule will update the logging destination of all existing ELBs to use the new LZA buckets.
 
+### CloudTrail Logs
+LZA creates a new Trail with a similar configuration than the one used by ASEA. The ASEA Trail is removed during the finalization step after running `yarn run post-migration remove-org-cloudtrail`.
+
+- The LZA trail uses the same S3 destination (central log bucket) but a different prefix (LZA: `cloudtrail-organization`; ASEA: `orgId (e.g. 0-a1a1a1aa1)`)
+- The LZA trail uses a different CloudWatch Log Group (LZA: `ASEA-cloudtrail-logs`; ASEA: `/ASEA/CloudTrail`)
+
+!!! Important
+    When using AWS Control Tower, the main management event trail is managed by Control Tower and is not affected by the upgrade. In that case above comments only apply to the ASEA managed Trail for S3 Data Event. When NOT using AWS Control Tower, ASEA manages a single Trail with management events and S3 data events.
+
 ## Customer Managed Keys
 There are differences between how ASEA and LZA manage AWS KMS keys to provide encryption at rest capabilities for resources deployed by the solution. Detailed documentation is available in the [Customer Managed Keys - Comparison of ASEA and LZA](./kms.md) document.
 

src/mkdocs/docs/lza-upgrade/preparation/prereq-config.md

@@ -20,7 +20,9 @@ Before running the upgrade tools, ensure you meet the following requirements:
 !!! note "Environment Requirements"
     ✅ **Recommended Environment:** Linux or MacOS with a Bash-like shell
 
-    ⚠️ **Important Note:** Windows compatibility is limited as tools have not been extensively tested on this platform
+    ⚠️ **Important Note:** Windows compatibility is limited as tools have not been extensively tested on this platform. All the upgrade tools SHOULD be run on a Unix-based shell.
+
+    You can use an EC2 instance in your AWS accounts to run the tools.
 
 
 #### Verify npm installation

src/mkdocs/docs/lza-upgrade/upgrade/finalize.md

@@ -22,14 +22,15 @@ This step will perform post upgrade actions which includes following
 - Marks duplicate CloudWatch Metrics resources for removal. `remove-cloudwatch-metrics`
 - Marks duplicate Budget resources for removal. `remove-budgets`
 - Marks duplicate logging resources for removal. `remove-logging`
+- Marks duplicate CloudTrail configurations for removal. `remove-org-cloudtrail`
 
 Each of the above steps has a corresponding flag that can be set during the post-migration step. These flags determine which actions are performed by the post-migration step.
 
 ## Post upgrade Commands
 
 ```bash
 cd <root-dir>
-yarn run post-migration remove-stack-outputs copy-certificates remove-sns-resources remove-asea-config-rules remove-cloudwatch-alarms remove-cloudwatch-metrics remove-budgets remove-logging
+yarn run post-migration remove-stack-outputs copy-certificates remove-sns-resources remove-asea-config-rules remove-cloudwatch-alarms remove-cloudwatch-metrics remove-budgets remove-logging remove-org-cloudtrail
 ```
 
 After the commands has been run, go the the CodePipeline console and release the `ASEA-Pipeline`. Resources that have been flagged for removal will be deleted in the `ImportAseaResources` stage.
@@ -43,6 +44,14 @@ Change the setting in the `global-config.yaml` file and run the LZA pipeline.
 terminationProtection: true
 ```
 
+## Use of Opt-in regions
+
+If you have AWS Opt-in regions, such as `ca-west-1` enabled in your landing zone, you should set the [enableOptInRegions](https://awslabs.github.io/landing-zone-accelerator-on-aws/latest/typedocs/interfaces/___packages__aws_accelerator_config_lib_models_global_config.IGlobalConfig.html#enableOptInRegions) option by adding the following line in your `global-config.yaml` file. This will ensure the opt-in regions are automatically enabled when you create new accounts.
+
+```
+enableOptInRegions: true
+```
+
 ## Upgrade complete
 
 At this point the upgrade to LZA is complete. Further updates to the environment will require updating the LZA configuration and then executing the LZA pipeline.

src/mkdocs/docs/lza-upgrade/upgrade/install-lza.md

@@ -20,7 +20,7 @@ yarn run lza-prep
 
 ## Installing the LZA Pipeline Confirmation
 
-Navigate to the AWS CloudFormation console and confirm that the stack named `<prefix-name>-Installer` deployed successfully.
+Navigate to the AWS CloudFormation console and confirm that the stack named `AWSAccelerator-InstallerStack` deployed successfully.
 
 ## Run the LZA Pipeline
 

src/mkdocs/docs/lza-upgrade/upgrade/optional-steps.md

@@ -15,8 +15,10 @@ If your workloads cannot tolerate a communication disruption to S3 and DynamoDB,
 
 Prior to executing the LZA upgrade
 
-- In the Shared Networking account, create Interface Endpoints for S3 and DynamoDB in the Endpoint VPC.
-    - Create a security group that allows HTTPS from anywhere (0.0.0.0/0)
+In the Shared Networking account, using the privilege pipeline role
+
+- Create a security group that allows HTTPS from anywhere (0.0.0.0/0)
+- Create Interface Endpoints for S3 and DynamoDB in the Endpoint VPC.
     - For S3
         - Do not select the option "Enable DNS Name"
         - Select the security group previously created