AWS Public Sector Blog

Self-hosting source code of the Landing Zone Accelerator on AWS

AWS branded background design with text overlay that says "Self-hosting source code of the Landing Zone Accelerator on AWS "

Some customers using Amazon Web Services (AWS) prohibit users from installing software from public sources. Recently, the Landing Zone Accelerator on AWS (LZA) solution added optional capabilities to support this use case. Instead of installing directly from the public LZA GitHub repository, which is the default installation path for most customers, LZA can be self-hosted from your own Amazon Simple Storage Service (Amazon S3) bucket.

This post shows the technical steps necessary to install LZA using Amazon S3.

Prerequisites

To complete the installation, you should have the following prerequisites:

  • Mandatory AWS accounts to use for LZA
  • Basic working knowledge of Git and NodeJS
  • NodeJS 18.x
  • Yarn dependency manager
  • AWS CLI v2.x

Solution overview

Installing the LZA happens in multiple parts. First, the AWS CloudFormation installer template configures an AWS CodePipeline, called AWSAccelerator-Installer, with the LZA source code, which must be customized for self-hosting. The installer pipeline builds the LZA source code and creates another AWS CodePipeline, called AWSAccelerator-Pipeline, to deploy to your configured AWS accounts.

You can customize the LZA source code for self-hosting by taking the following straightforward steps:

  1. Create an Amazon S3 bucket with versioning enabled.
  2. Download the LZA source code.
  3. Zip the customized LZA source code and copy it to the Amazon S3 bucket you created.
  4. Build the customized LZA CloudFormation installer template.
  5. Deploy the stack.

Figure 1. Steps to self-host source code of the Landing Zone Accelerator on AWS. The major components are an Amazon S3 bucket, AWS CloudFormation, and AWS CodePipeline.

Solution walkthrough: Self-hosting source code of the Landing Zone Accelerator on AWS

To customize the LZA source code for self-hosting, complete the following steps:

Step 1: Create an Amazon S3 bucket with versioning.

  1. Sign in to the LZA management account and navigate to the Amazon S3 console.
  2. Choose Create bucket.
  3. Provide a bucket name specific to your AWS account.
  4. In Bucket Versioning, choose Enable.
  5. Confirm the bucket create.

We recommend that you use the default Amazon S3 encryption. However, if you choose to disable the bucket key and use your own key from AWS Key Management Service (AWS KMS) instead, you also must pass the Amazon Resource Name (ARN) of your KMS key when synthesizing the template, as described in step 4.

You can now configure any additional bucket settings for your environment, such as the aws:SecureTransport condition.

Step 2: Download the LZA Source Code

To begin, make a copy of the public LZA GitHub repository and switch to the latest version, 1.11.0 for example:

git clone https://github.com/awslabs/landing-zone-accelerator-on-aws

git switch release/v1.11.0

At this point, you can run any procedure that is required by your internal standards, such as a security scan on the LZA source code. Optionally, you can mirror the public LZA GitHub into your internal Git service and configure a continuous integration (CI) script or action for this step and the following steps.

Step 3: Create the LZA source code zip and upload to S3

Zip the entire LZA directory, making sure that the source directory is present at the top level of the .zip. Copy the .zip to your versioned S3 bucket created previously:

LZAV=v1.11.0

zip -q -T -r ../$LZAV . # quiet, test integrity, recursive

aws s3 cp ../$LZAV s3://$MY_VERSIONED_S3_BUCKET/release/$LZAV.zip

If using a CI script, make sure you have AWS credentials configured with permissions to the Amazon S3 bucket.

Step 4: Create customized LZA installer template

Create a customized LZA installer template with the use-s3-source feature flag enabled:

cd source

yarn install && yarn build

cd packages/\@aws-accelerator/installer/

cdk synth --context use-s3-source=true

ls cdk.out/AWSAccelerator-InstallerStack.template.json

If you are using your own AWS KMS key for the S3 bucket, in the above cdk line you also must pass your KMS key ARN when synthesizing the template:

cdk synth --context use-s3-source=true --context s3-source-kms-key-arn=arn:aws:kms:us-east-1:000000000000:key/aaaaaaaa-1111-bbbb-2222-cccccc333333

Optional step: CI template

You can customize the following example CI script, which completes the preceding steps:

image: public.ecr.aws/docker/library/node:18

stages:
- build-zip

installer-s3-source:
  stage: build-zip
  before_script:
    # quiet output, only errors
    - apt update -qq > /dev/null
    - apt-cache -qq gencaches > /dev/null
    - apt-get install -y --no-install-recommends -qq jq zip awscli
  script:
    - "export NODE_OPTIONS=--max_old_space_size=16384"
    - "export version=$(cat source/package.json | jq -r '.version')"
    - "zip -q -T -r $CI_PROJECT_DIR/${version}.zip . # quiet, test integrity, recursive"
    - "cd source"
    - "npm install yarn@1.22.22"
    - "yarn install"
    - "yarn build"
    - "cd packages/@aws-accelerator/installer"
    - "yarn run cdk synth --context use-s3-source=true > /dev/null"
    - "cp cdk.out/AWSAccelerator-InstallerStack.template.json $CI_PROJECT_DIR"
  artifacts:
    name: "installer-s3-source"
    when: on_success
    paths:
      - "*zip"
      - AWSAccelerator-InstallerStack.template.json
JSON

Step 5: Install and troubleshoot

You can now use your customized LZA installer template with the RepositoryBucketName parameter set to your Amazon S3 bucket, which has the self-hosted source code for LZA.

Each part of the LZA installation process has a place to check for any issues:

  • For issues with using the installer template, use the Detect Root Cause button on the AWS CloudFormation Stack Events page.
  • For issues with the AWSAccelerator-Installer pipeline, use the AWS CodePipeline detail page.
  • For issues with the AWSAccelerator-Installer Build stage, use the AWS CodeBuild logs.
  • For issues with deploying LZA, refer to the Known issue resolution section of the Landing Zone Accelerator Implementation Guide.

Conclusion

Visit the LZA implementation guide for further details on all that Landing Zone Accelerator on AWS offers. To remove LZA resources, see the Uninstall the solution section.

If you are looking for support in designing, building, and operating a landing zone, AWS Professional Services, AWS Managed Services, and the Amazon Partner Network can help.

If you would like to find out more, please contact the AWS Public Sector team.