How to validate Landing Zone Accelerator (LZA) configuration files locally?

Step 1: Local Development - Installations

To set up the validator locally, you need to have the necessary local installations. If you already have the necessary installations, you can proceed to the next step 2.

Install NPM

npm install -g npm

📖 NPM Installation Guide

Install Yarn

npm install --global yarn

📖 Yarn Installation Guide

Install CDK

npm install -g aws-cdk

📖 CDK Getting Started Guide

Install Python

curl -o get-pip.py https://bootstrap.pypa.io/get-pip.py

Step 2: Local Development - Prerequisites

2.1 Clone AWS Accelerator Config Locally

Clone your configuration files locally. This folder will contain the configuration files and their necessary dependencies.

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

2.2 Get Credentials for the Account

1. Login to your IAM Identity Center (AWS SSO) to retrieve temporary credentials
2. Set the environment using temporary credentials
3. Retrieve temporary credentials through the command line or programmatic access

Note: Make sure to use either Option 1 (Set AWS environment variables) or Option 2 (Add a profile to your AWS credentials file) to access AWS resources programmatically or from the AWS CLI. Please refer below attached image for more details.

Optional: Verify whether the identity matches the correct account:

aws sts get-caller-identity

Optional: Set AWS profile only if you are using Option 2 (Add a profile to your AWS credentials file):

export AWS_PROFILE=<your-profile-name>

Step 3: Building the Tool

This step involves building LZA locally using the source code available at /landing-zone-accelerator-on-aws/source from the GitHub repository that was cloned in Step 2.1.

cd ~<local-dir>/landing-zone-accelerator-on-aws/source
yarn install && yarn build

Step 4: Run Local Synth

Running the synth locally provides debugging opportunities and enables the bootstrap stage to be executed locally instead of waiting for the CodePipeline to reach that stage. This local synth can expedite exploration during iteration of the configuration to ensure syntax accuracy or overall correctness.

4.1 Basic Synth

cd source/packages/@aws-accelerator/accelerator
yarn run ts-node --transpile-only cdk.ts synth \
  --require-approval never \
  --config-dir $LZA_CONFIG_DIR_LOCATION \
  --partition aws

Note: If you are using Option 1 (Set AWS environment variables) from the above Step 2.2 then you can use above command to run local synth. However, if you are using Option 2 (Add a profile to your AWS credentials file) then you would need to specify export AWS_PROFILE=<your-profile-name> command before running above synth command from Step 4.1.

4.2 Stage-Specific Synth

You can also run this against a specified stage:

cd source/packages/@aws-accelerator/accelerator
yarn run ts-node --transpile-only cdk.ts synth \
  --stage $STAGE \
  --config-dir $LZA_CONFIG_DIR_LOCATION
  --partition aws

Note: Valid stage names for $STAGE can be found in: landing-zone-accelerator-on-aws/source/packages/@aws-accelerator/accelerator/lib/accelerator-stage.ts

Step 5: Validate Locally

Validation can be performed locally to test the syntax of the configuration files.

cd landing-zone-accelerator-on-aws/source
yarn install
yarn validate-config $LZA_CONFIG_DIR_LOCATION

Important:

• Replace $STAGE with the appropriate stage name from the accelerator-stage.ts file
• Replace $LZA_CONFIG_DIR_LOCATION with the path to your configuration directory

This validation process will help ensure your configuration files are syntactically correct before deploying them through the pipeline.

Related Articles:

1. landing-zone-accelerator-on-aws GitHub Repo
2. How do I use the IAM Identity Center and the AWS access portal?
3. Getting IAM Identity Center user credentials for the AWS CLI or AWS SDKs