feat(lza-upgrade): add doc and options to set which LZA version to install (#1301)

* chore: doc to use specific LZA version

* add option to configure a different installer stack

* add doc to use installer stack for a specific version

Author: oliviergaumond

reference-artifacts/Custom-Scripts/lza-upgrade/src/config.ts

@@ -36,4 +36,6 @@ export interface Config {
   skipDriftDetection?: boolean;
   localConfigFilePath?: string;
   enableTerminationProtection?: boolean;
+  lzaInstallerTemplateBucket?: string
+  lzaInstallerTemplateKey?: string
 }

reference-artifacts/Custom-Scripts/lza-upgrade/src/preparation.ts

@@ -55,7 +55,8 @@ export class Preparation {
   }
 
   async prepareLza() {
-    await getLZAInstallerStackTemplate('solutions-reference');
+    await getLZAInstallerStackTemplate(this.config.lzaInstallerTemplateBucket ?? 'solutions-reference',
+      this.config.lzaInstallerTemplateKey ?? 'landing-zone-accelerator-on-aws/latest/AWSAccelerator-InstallerStack.template');
     await putLZAInstallerStackTemplate(this.config.aseaConfigBucketName, this.homeRegion);
     const installerStackParameters: InstallerStackParameters = {
       repositorySource: this.config.lzaCodeRepositorySource ?? 'github',

reference-artifacts/Custom-Scripts/lza-upgrade/src/preparation/aws-lza.ts

@@ -147,12 +147,12 @@ export async function createLZAInstallerCloudFormationStack(
   }
 }
 
-export async function getLZAInstallerStackTemplate(bucketName: string) {
+export async function getLZAInstallerStackTemplate(bucketName: string, objectKey: string) {
   const s3Client = new S3Client({ endpoint: 'https://s3.amazonaws.com', region: 'us-east-1' });
   const template = await s3Client.send(
     new GetObjectCommand({
       Bucket: bucketName,
-      Key: 'landing-zone-accelerator-on-aws/latest/AWSAccelerator-InstallerStack.template',
+      Key: objectKey,
     }),
   );
 

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

@@ -85,3 +85,27 @@ ORDER BY
 ```
 
 For more information about LZA related Quotas, refer to the [LZA Documentation about Quotas](https://docs.aws.amazon.com/solutions/latest/landing-zone-accelerator-on-aws/quotas.html) as well as this note about [CodeBuild concurrency](https://docs.aws.amazon.com/solutions/latest/landing-zone-accelerator-on-aws/prerequisites.html#update-codebuild-conncurrency-quota)
+
+## What version of LZA will be installed?
+
+By default, the LZA upgrade tools install the latest LZA official release. To specify a version to use, follow these instructions:
+
+1. Run `yarn migration-config` from the [Preparation phase](./preparation/prereq-config.md#configuration)
+2. Edit the `src/input-config/input-config.json` file
+3. Add the following property to the file to specify which branch to use: `"lzaCodeRepositoryBranch": "release/<version>"`
+4. Add the following property to specify the path of the CloudFormation installer template from the solution reference bucket `"lzaInstallerTemplateKey": "landing-zone-accelerator-on-aws/<version>/AWSAccelerator-InstallerStack.template"`
+5. Follow the remaining steps of the upgrade. This configuration will be used when you install LZA using the `yarn run lza-prep` command in the [Upgrade phase](./upgrade/install-lza.md)
+
+!!! info
+    The `lzaCodeRepositoryBranch` and `lzaInstallerTemplateKey` should match the same LZA version. For example, to install version `v1.12.6` you should have the following properties in your `input-config.json` file.
+
+    ```json
+    "lzaCodeRepositoryBranch": "release/v1.12.6",
+    "lzaInstallerTemplateKey": "landing-zone-accelerator-on-aws/v1.12.6/AWSAccelerator-InstallerStack.template"
+    ```
+
+    The latest CloudFormation installer template is available from the [LZA Implementation Guide](https://docs.aws.amazon.com/solutions/latest/landing-zone-accelerator-on-aws/aws-cloudformation-template.html). Previous versions are accessible by changing the version number in the Url.
+
+
+!!! tip "When to use a specific version"
+    If you are upgrading Non-Production and Production environments we recommend that you use the same version for both environments to replicate the same results. You can update to the latest LZA version once you upgraded from ASEA to LZA.

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

@@ -96,6 +96,8 @@ yarn run migration-config
 !!! info
     By default the upgrade tool uses `ca-central-1` as the home region. If you use a different home region you need to set the AWS_REGION environment variable before running `migration-config`. e.g. `AWS_REGION=eu-west-1 yarn run migration-config`
 
+    By default the upgrade tool install the latest LZA official release. To specify a version to use see the [FAQ](../faq.md#what-version-of-lza-will-be-installed)
+
 ??? abstract "Detailed information"
     This command will also deploy a CloudFormation template and create two CodeCommit repositories. The CloudFormation template will create an S3 bucket for the resource mapping files. The first CodeCommit repository will also be used for the resource mapping files. The second CodeCommit repository will be used for the Landing Zone Accelerator configuration files that will be created in a later step.