ASEA to LZA Documentation updates (#1279)

* add troubleshooting entries

* formatting

* updated fixed issues in 1.12

* ASEA/LZA difference for ELB logging buckets

* update python libraries

* doc updates

* add known issue about resource limit

* grammar and typos

* updated broken link

Author: oliviergaumond

reference-artifacts/Custom-Scripts/lza-upgrade/tools/network-drift-detection/lza-upgrade-check.py

@@ -627,13 +627,11 @@ def compare_route_table(crt, drt):
                         {"Route": cr['destination'], "Reason": "Not matched to firewall instance"})
             else:
                 logger.error(f"Route target {cr['target']} is not supported!")
-                drift.append({"Route": cr['destination'], "Reason": f"Route target {
-                             cr['target']} is not supported!"})
+                drift.append({"Route": cr['destination'], "Reason": f"Route target {cr['target']} is not supported!"})  # nopep8
         else:
             # this should not be possible!
             logger.error(f"More than one route with destination {cr['destination']} is deployed!")  # nopep8
-            drift.append({"Route": cr['destination'], "Reason": f"More than one route with destination {
-                         cr['destination']} found"})
+            drift.append({"Route": cr['destination'], "Reason": f"More than one route with destination {cr['destination']} found"})  # nopep8
 
     # check if there are route entries deployed that are not in the config
     for dr in dRoutes:
@@ -642,8 +640,7 @@ def compare_route_table(crt, drt):
                 f"Route {dr['DestinationCidrBlock']} is a VPC peering route. Skipping check")
             continue
 
-        cr = [r for r in cRoutes if r['destination']
-              == dr['DestinationCidrBlock']]
+        cr = [r for r in cRoutes if r['destination'] == dr['DestinationCidrBlock']]
         if len(cr) == 0:
             logger.warning(f"Route {dr['DestinationCidrBlock']} exists in deployed route table but not found in config")  # nopep8
             drift.append(

reference-artifacts/Custom-Scripts/lza-upgrade/tools/network-drift-detection/requirements.txt

@@ -1,7 +1,7 @@
-boto3==1.35.40
-botocore==1.35.40
+boto3==1.38.1
+botocore==1.38.2
 jmespath==1.0.1
 python-dateutil==2.9.0.post0
-s3transfer==0.10.3
-six==1.16.0
-urllib3==2.2.3
+s3transfer==0.12.0
+six==1.17.0
+urllib3==2.4.0

src/mkdocs/docs/lza-upgrade/asea-resource-handlers.md

@@ -2,39 +2,39 @@
 
 In order to accomplish upgrading from ASEA to LZA, the solution relies on a concept called ASEA Resource Handlers. These resource handlers utilize the [CFN Include module](https://docs.aws.amazon.com/cdk/v2/guide/use_cfn_template.html) to allow the LZA engine to manage ASEA resources in their original CloudFormation stacks. By using the CFN Include Module, the LZA application can modify certain properties of CloudFormation constructs. The current state of supported resources can be found in the table below:
 
-|Resource Type	|Resource Deletion Supported	|Resource Update Supported	|Modifiable Attributes	|	|
-|---	|---	|---	|---	|---	|
-|Application Load Balancers	|FALSE	|FALSE	|	|	|
-|EC2 Firewall Instance (Fortinet)	|FALSE	|FALSE	|	|	|
-|ELB Target Group	|FALSE	|FALSE	|	|	|
-|IAM Groups	|TRUE	|TRUE	|Group Name </br> Managed Policy Arns	|	|
-|IAM Managed Policies	|TRUE	|TRUE	|Managed Policy Name </br> Managed Policy Document	|	|
-|IAM Roles	|TRUE	|TRUE	|Permissions Boundary </br> Managed Policy Arns </br> Assume Role Policy Document </br> Instance Profile	|	|
-|IAM Users	|TRUE	|TRUE	|Groups </br> Permissions Boundary	|	|
-|Internet Gateway (IGW)	|FALSE	|FALSE	|	|	|
-|ManagedAD	|FALSE	|FALSE	|	|	|
-|NACL Subnet Associations	|FALSE	|TRUE	|NACL Id </br> Subnet Id	|	|
-|NAT Gateway	|FALSE	|TRUE	|Subnet Id	|	|
-|Network Firewall	|TRUE	|TRUE	|Firewall Logging Configuration	|	|
-|Network Firewall Policy	|TRUE	|FALSE	|	|	|
-|Network Firewall Rule Group	|TRUE	|FALSE	|	|	|
-|Route53 Hosted Zone	|FALSE	|FALSE	|	|	|
-|Route53 Query Logging Association	|FALSE	|FALSE	|	|	|
-|Route53 Record Set	|FALSE	|FALSE	|	|	|
-|Route53 Resolver Endpoint	|FALSE	|FALSE	|	|	|
-|Security Groups	|FALSE	|TRUE	|Security Group Ingress Rules </br> Security Group Egress Rules	|	|
-|Shared Security Group	|FALSE	|FALSE	|	|	|
-|SSM Association	|FALSE	|FALSE	|	|	|
-|SSM Resource Data Sync	|FALSE	|FALSE	|	|	|
-|Subnets	|FALSE	|TRUE 	|Subnet CIDR Block </br> Subnet Availability Zone </br> Subnet Map Public IP on Launch	|	|
-|Transit Gateway Associations	|FALSE	|FALSE	|	|	|
-|Transit Gateway Black Hole Routes	|FALSE	|FALSE	|	|	|
-|Transit Gateway Propagations	|FALSE	|FALSE	|	|	|
-|Transit Gateway Route Tables	|FALSE	|FALSE	|	|	|
-|Transit Gateway Routes	|FALSE	|FALSE	|	|	|
-|Transit Gateways	|FALSE	|TRUE	|Amazon Side ASN </br> Auto Accept Shared Attachments </br> Default Route Table Associations </br> Default Route Table Propagations </br> DNS Support </br> VPN ECMP Support	|	|
-|Virtual Private Gateway	|FALSE	|TRUE	|Amazon Side ASN	|	|
-|VPC	|FALSE	|TRUE	|CIDR Blocks </br> Enable DNS Host Names </br> Enable DNS Support </br> Instance Tenancy 	|	|
-|VPC Endpoint	|TRUE	|FALSE	|None, Including associated security group. Must re-create endpoint |	|
-|VPC Endpoint (Gateway)	|FALSE	|TRUE	|Route Table Ids	|	|
-|VPC Peering Connection	|FALSE	|FALSE	|	|	|
+|Resource Type	|Resource Deletion Supported	|Resource Update Supported	|Modifiable Attributes	|
+|---	|---	|---	|---	|
+|Application Load Balancers	|FALSE	|FALSE	|	|
+|EC2 Firewall Instance (Fortinet)	|FALSE	|FALSE	|	|
+|ELB Target Group	|FALSE	|FALSE	|	|
+|IAM Groups	|TRUE	|TRUE	|Group Name </br> Managed Policy Arns	|
+|IAM Managed Policies	|TRUE	|TRUE	|Managed Policy Name </br> Managed Policy Document	|
+|IAM Roles	|TRUE	|TRUE	|Permissions Boundary </br> Managed Policy Arns </br> Assume Role Policy Document </br> Instance Profile	|
+|IAM Users	|TRUE	|TRUE	|Groups </br> Permissions Boundary	|
+|Internet Gateway (IGW)	|FALSE	|FALSE	|	|
+|ManagedAD	|FALSE	|FALSE	|	|
+|NACL Subnet Associations	|FALSE	|TRUE	|NACL Id </br> Subnet Id	|
+|NAT Gateway	|FALSE	|TRUE	|Subnet Id	|
+|Network Firewall	|TRUE	|TRUE	|Firewall Logging Configuration	|
+|Network Firewall Policy	|TRUE	|FALSE	|	|
+|Network Firewall Rule Group	|TRUE	|FALSE	|	|
+|Route53 Hosted Zone	|FALSE	|FALSE	|	|
+|Route53 Query Logging Association	|FALSE	|FALSE	|	|
+|Route53 Record Set	|FALSE	|FALSE	|	|
+|Route53 Resolver Endpoint	|FALSE	|FALSE	|	|
+|Security Groups	|FALSE	|TRUE	|Security Group Ingress Rules </br> Security Group Egress Rules	|
+|Shared Security Group	|FALSE	|FALSE	|	|
+|SSM Association	|FALSE	|FALSE	|	|
+|SSM Resource Data Sync	|FALSE	|FALSE	|	|
+|Subnets	|FALSE	|TRUE 	|Subnet CIDR Block </br> Subnet Availability Zone </br> Subnet Map Public IP on Launch	|
+|Transit Gateway Associations	|FALSE	|FALSE	|	|
+|Transit Gateway Black Hole Routes	|FALSE	|FALSE	|	|
+|Transit Gateway Propagations	|FALSE	|FALSE	|	|
+|Transit Gateway Route Tables	|FALSE	|FALSE	|	|
+|Transit Gateway Routes	|FALSE	|FALSE	|	|
+|Transit Gateways	|FALSE	|TRUE	|Amazon Side ASN </br> Auto Accept Shared Attachments </br> Default Route Table Associations </br> Default Route Table Propagations </br> DNS Support </br> VPN ECMP Support	|
+|Virtual Private Gateway	|FALSE	|TRUE	|Amazon Side ASN	|
+|VPC	|FALSE	|TRUE	|CIDR Blocks </br> Enable DNS Host Names </br> Enable DNS Support </br> Instance Tenancy 	|
+|VPC Endpoint	|TRUE	|FALSE	|None, Including associated security group. Must re-create endpoint |
+|VPC Endpoint (Gateway)	|FALSE	|TRUE	|Route Table Ids	|
+|VPC Peering Connection	|FALSE	|FALSE	|	|

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

@@ -46,7 +46,7 @@ For example several parameters are created to reference networking resources.
 !!! tip
     For AWS accounts created before the upgrade, both sets of parameters will co-exist. For new accounts ad resources created after the upgrade, only the LZA version of the parameters will exist.
 
-Refer to the [Landing Zone Accelerator Implementation Guide](https://docs.aws.amazon.com/solutions/latest/landing-zone-accelerator-on-aws/accessing-solution--outputs-through-parameter-store.html) for a full list of Parameter Store outputs supported by LZA.
+Refer to the [Landing Zone Accelerator Implementation Guide](https://docs.aws.amazon.com/solutions/latest/landing-zone-accelerator-on-aws/developer-guide.html#accessing-solution--outputs-through-parameter-store) for a full list of Parameter Store outputs supported by LZA.
 
 ## Centralized logging
 LZA uses the same centralized logging architecture than ASEA to consolidate logs in a central S3 bucket in the Log Archive account. During the upgrade the configuration and dynamic partitioning rules are adapted to keep the same logging structure. If you have external integrations that depend on the logging structure and format, you should closely monitor the logs during the upgrade and review the current section to identify if the differences can impact your integration.
@@ -75,6 +75,8 @@ When Security Hub is configured to send logs to CloudWatch, in ASEA the forwardi
 
 In LZA, the forwarding rule and CloudWatch Log Groups are created in every account and enabled region. This will result in additional logs being sent to CloudWatch and the centralized S3 logging bucket.
 
+### 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.
 
 ## 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/faq.md

@@ -4,11 +4,11 @@
 
 The upgrade is designed to be as transparent and automated as possible. Only resources initially deployed by ASEA are touched during the upgrade, any resources deployed outside the accelerator and in workloads accounts are not impacted during the upgrade.
 
-Changes to the shared networking resources managed by the accelerator can have an impact on the availability of workloads using the shared VPCs and perimeter resources. During the upgrade process, LZA creates new route tables and NACLs and associates them with the existing subnets to replace the previous ASEA route tables and NACLs. We recommend customers plan for a one to two minute network disruption for the traffic going through the Perimeter VPC.
+Changes to the shared networking resources managed by the accelerator may have an impact on the availability of workloads using the shared VPCs and perimeter resources. During the upgrade process, LZA creates new route tables and NACLs and associates them with the existing subnets to replace the previous ASEA route tables and NACLs. We recommend customers plan for a one to two minute network disruption for the traffic going through the Perimeter VPC.
 
 - The LZA route table and NACLs are re-created based on the ASEA configuration. It is critical to identify drift or any manual modifications done to these resources prior to the upgrade.
-- When the route tables are replaced in the NetworkVPC stage of the LZA installation, minimal packet loss (i.e. few seconds) can be observed. This affect all traffic going through the Transit Gateway.
-- For deployments using AWS Network Firewall, the routes targeting the network firewall endpoints are re-created in the NetworkVpcEndpointsStack that is deployed immediately after the NetworkVPCStack. This cause a network disruption of all ingress/egress traffic going through the Perimeter VPC between 1 and 2 minutes.
+- When the route tables are replaced in the NetworkVPC stage of the LZA installation, minimal packet loss (i.e. few seconds) can be observed. This affects all traffic going through the Transit Gateway.
+- For deployments using AWS Network Firewall, the routes targeting the network firewall endpoints are re-created in the NetworkVpcEndpointsStack that is deployed immediately after the NetworkVPCStack. This causes a network disruption of all ingress/egress traffic going through the Perimeter VPC between 1 and 2 minutes.
 - For deployments using third-party Firewalls (i.e. FortiGate), the routes targeting the firewall ENIs are re-created in the NetworkAssociationsGwlbStack. This doesn't affect workload traffic flowing through the firewalls but can impact connectivity to the firewall management interface.
 - There is a period between the **NetworkVPC** and **PostImportASEAResources** stages where route tables to VPC Gateway Endpoints for S3 and DynamoDB are not available. See the section on [Optional preparation steps](./upgrade/optional-steps.md#configure-interface-endpoints-for-s3-and-dynamodb) for more details and recommended workaround.
 
@@ -20,7 +20,7 @@ The preferred resolution is to align the ASEA configuration to incorporate the m
 
 If this is not possible, you should record all route table information before the upgrade to identify manually created entries. After the upgrade is complete, these entries need to be recreated.
 
-Note: Transit Gateway route tables are not replaced during the upgrade, theses guidelines only apply to subnet route tables.
+Note: Transit Gateway route tables are not replaced during the upgrade, these guidelines only apply to subnet route tables.
 
 !!! tip
     There is a script available to help detect drift on networking resources that are not detected by CloudFormation. The script is available in the [tools/network-drift-detection](https://github.com/aws-samples/aws-secure-environment-accelerator/tree/main/reference-artifacts/Custom-Scripts/lza-upgrade/tools/network-drift-detection/) folder in the ASEA to LZA upgrade tools.
@@ -32,12 +32,12 @@ As covered in the [Feature specific considerations](./comparison/feature-specifi
 
 Review the related route table entries in the network-config.yaml file and compare the entries with the entries of the route tables currently deployed in your environment. Make the necessary modifications in network-config.yaml to match the current configuration. Reference the [RouteTableEntryConfig](https://awslabs.github.io/landing-zone-accelerator-on-aws/latest/typedocs/latest/interfaces/___packages__aws_accelerator_config_lib_models_network_config.IRouteTableEntryConfig.html) documentation for more details on how to configure route tables in LZA.
 
-In this scenario you won't be able to use the `gatewayLoadBalancerEndpoint` destination type to reference a GWLB that was not deployed by LZA. As an alternative you can use the `networkInterface` type to directly reference the ENIs of the GWLB endpoints. Please note, that the LZA route tables are created and associated in the NetworkVPC stack, but the route entries of type `networkInterface` are created in the NetworkAssociations stack which is triggered later in the pipeline, resulting in a period of time where the route entries will be missing.
+In this scenario, you won't be able to use the `gatewayLoadBalancerEndpoint` destination type to reference a GWLB that was not deployed by LZA. As an alternative you can use the `networkInterface` type to directly reference the ENIs of the GWLB endpoints. Please note, that the LZA route tables are created and associated in the NetworkVPC stack, but the route entries of type `networkInterface` are created in the NetworkAssociations stack which is triggered later in the pipeline, resulting in a period of time where the route entries will be missing.
 
 Another alternative is to manually add the missing route entries to the LZA route tables as soon as the NetworkVPC stage completes to minimize network downtime.
 
 
-## Do you recommend to have specific monitoring in place for the upgrade?
+## Do you recommend having specific monitoring in place for the upgrade?
 
 We highly recommend that you monitor the availability of all your workloads deployed in the Landing Zone as well as the main network flows to be alerted of any impact during the upgrade process.
 

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

@@ -2,7 +2,7 @@
 
 ## Overview
 
-The AWS Secure Environment Accelerator (ASEA) launched in 2020 in order for Canadian customers to implement landing zones that complied with the Canadian Centre for Cyber Security Medium Cloud (CCCS-M) profile. As our services continue to evolve, a long-term strategy and plan was developed in 2021 to incorporate features and lessons learned from ASEA, as part of this strategy AWS launched Landing Zone Accelerator on AWS (with Control Tower) which is now the preferred solution for accelerating customer landing zones globally.
+The AWS Secure Environment Accelerator (ASEA) launched in 2020 in order for Canadian customers to implement landing zones that complied with the Canadian Centre for Cyber Security Medium Cloud (CCCS-M) profile. As our services continued to evolve, a long-term strategy and plan were developed in 2021 to incorporate features and lessons learned from ASEA, as part of this strategy AWS launched Landing Zone Accelerator on AWS (with Control Tower) which is now the preferred solution for accelerating customer landing zones globally.
 
 This technical guide assists customers in performing an in-place upgrade from ASEA Landing Zone to Landing Zone Accelerator (LZA). The target audience is technical personnel responsible for the deployment and operational management of landing zones.
 
@@ -16,7 +16,7 @@ The upgrade process is executed through a series of command-line scripts, design
 
 ## High-level process
 
-In order to perform a successful upgrade, there is a sequence of tasks that must be completed before the upgrade can begin. The first task is generating the configuration file for the upgrade tool. Subsequent tasks check that all ASEA resources currently deployed are in the correct state, update ASEA to the latest version, and remediate any resource drift of deployed ASEA resources using the provided scripts. Once the resources are remediated and ASEA is upgraded to the latest version, customers will then enable a new configuration option in the ASEA configuration file that will instruct the ASEA state machine to prepare the environment for upgrade by removing resources that are only necessary to run the ASEA state machine, and other ASEA specific tasks. This will also effectively disable all ASEA CloudFormation custom resources from modifying any of the resources that have been deployed. After the final ASEA state machine run, the ASEA installer stack can be removed from the environment to completely disable and remove ASEA.
+To perform a successful upgrade, there is a sequence of tasks that must be completed before the upgrade can begin. The first task involves generating the configuration file for the upgrade tool. Subsequent tasks check that all ASEA resources currently deployed are in the correct state, update ASEA to the latest version, and remediate any resource drift of deployed ASEA resources using the provided scripts. Once the resources are remediated and ASEA is upgraded to the latest version, customers will then enable a new configuration option in the ASEA configuration file that will instruct the ASEA state machine to prepare the environment for upgrade by removing resources that are only necessary to run the ASEA state machine, and other ASEA specific tasks. This will also effectively disable all ASEA CloudFormation custom resources from modifying any of the resources that have been deployed. After the final ASEA state machine run, the ASEA installer stack can be removed from the environment to completely disable and remove ASEA.
 
 Once the ASEA installer stack has been removed, the customer will run a script that will create a mapping of every resource in every account and region that ASEA has deployed, and store that file in Amazon S3 and AWS CodeCommit. This mapping will be used by the Landing Zone Accelerator (LZA) to identify ASEA specific resources that must be modified or referenced in later stages of the upgrade. Once the mapping file is generated, the LZA configuration file generation script can also be run. This file in conjunction with the mapping, will be used to create the LZA configuration files during the upgrade.