AWS luminarlz CLI

A lean, opinionated CLI to make deployment and development with the Landing Zone Accelerator on AWS (LZA) easier.

What it does and doesn't and what you need to know

• It provides a blueprint to easily set up a well-architected AWS landing zone.
• It helps you with the deployment and maintenance of the LZA.
• It does not add any new features to the LZA.
• In case you want, it lets you opt out and remove the dependency to the AWS luminarlz CLI completely.
• It uses LiquidJS to generate the LZA config files.
• It uses AWS CDK to generate the AWS Cloudformation templates used for the LZA customizations.
• It doesn't replace but consumes the LZA Core CLI by automatically cloning a local LZA checkout with the correct LZA version.
• It allows you to easily use LZA Core CLI features like LZA config validation, LZA Core Pipeline stage synthesis or LZA Core Pipeline stage deployment.
• It's not a free lunch and still requires you to know how various AWS libraries and services work together. Here are some readings to dive into:
  • The LZA architecture overview.
  • LZA is recommended to be used together with AWS Control Tower.
  • LZA supports deploying custom Cloudformation Stacks, StackSets and more.
  • An LZA installation comes with the Installer Pipeline & the Core Pipeline.

Architecture diagram

Usage

Initialize a new AWS landing zone

This is a step-by-step guide to initialize a new AWS landing zone using the luminarlz CLI.

We'll use the foundational blueprint that is heavily aligned with the Guidance for Establishing an Initial Foundation using Control Tower on AWS.

We recommend reading through the Guidance first as there are parts that require some manual steps and upfront planning like the root email strategy.

1. Make sure you have an AWS Organizations management account which fulfils the LZA prerequisites.
2. Make sure to deploy the LZA with the following settings:
   • Environment Configuration: Leave all the defaults, Control Tower Environment needs to be set to Yes.
   • Config Repository Configuration: Leave all the defaults and set Configuration Repository Location to s3.
3. Wait until the initial LZA is successfully deployed.
4. Configure your terminal with AWS administrator credentials for the Management AWS account.
5. Init the project using:

npx @superluminar-io/aws-luminarlz-cli init

6. Install the new dependencies:

npm install

7. Adapt the settings and fill in the open TODOS in the generated config.ts file.
8. Have a look at the generated README file as it contains further documentation on how to use the AWS luminarlz CLI.
9. Deploy your new LZA config using:

# You'll need the `Management` account credentials with administrator rights to be configured in your terminal.
npm run cli -- deploy

10. Make sure to start the AWSAccelerator-Pipeline manually after the initial deployment as the pipeline is not automatically started by the LZA.
11. Wait until the blueprint is successfully deployed, from now on the pipeline should start automatically after deploying a new LZA config.
12. Search for open TODO comments in the generated files and adapt them to your needs.

CLI reference

Run any command with --help to see its full options, e.g.:

npx @superluminar-io/aws-luminarlz-cli --help
npx @superluminar-io/aws-luminarlz-cli init --help

| Command | Description | |---------|-------------| | init | Generate a new project from a blueprint | | synth | Synthesize the LZA config and CDK customizations locally | | deploy | Synthesize and upload the LZA config to S3, triggering the LZA pipeline | | lza config validate | Validate the synthesized LZA config using the LZA Core CLI | | lza core bootstrap | Bootstrap the LZA bootstrap stage (e.g. when adding a new region) | | lza installer-version check | Check that the locally configured LZA version matches the deployed one | | lza installer-version update | Trigger a version update of the LZA Installer CloudFormation stack | | lza customizations-stack synth | Synthesize a single LZA customizations stack for a specific account | | lza customizations-stack deploy | Synthesize and deploy a single LZA customizations stack for a specific account | | lza stage synth | Synthesize a specific LZA pipeline stage (default: customizations) | | lza stage deploy | Synthesize and deploy a specific LZA pipeline stage (default: customizations) |

init options

| Option | Description | |--------|-------------| | --blueprint <name> | Blueprint to use. Defaults to foundational. Available blueprints: github.com/superluminar-io/aws-luminarlz-cli/tree/main/blueprints | | --accounts-root-email <email> | Root email address pattern for AWS accounts. Prompted interactively if not provided. | | --region <region> | AWS home region where the LZA is installed. Prompted interactively if not provided. | | --force | Overwrite existing files. |

LZA Core CLI

Some commands use the LZA Core CLI underneath. Running it requires a local checkout of the LZA repository — this is done automatically on first use and whenever the LZA version changes.

Add /.landing-zone-accelerator-on-aws-* to your .gitignore so these checkouts are not committed to your repository.

Development

Prerequisites

• Install the node version defined in .node-version.
• Install dependencies:

yarn projen

Running the CLI

During development, you can run the CLI without building it:

./src/index.ts

Build Instructions

The project uses Projen for build management. Make sure not to edit any files that are managed by Projen directly, as they will be overwritten on the next Projen run. Instead, make changes in the .projenrc.ts file. Files managed by Projen include a comment like: Generated by projen.

To build the project:

yarn build

To compile TypeScript files:

yarn compile

To package the project:

yarn package

Testing

Run all tests in the project:

yarn test

Run a single test file like this:

yarn test <test-file-path>

To run a single test like this:

yarn test -t "<test-name>"

Linting

Use ESLint for code linting:

yarn eslint

Commit messages and pull request titles

Commit messages and PR titles must follow the Conventional Commits format and use one of the allowed types: feat, fix, or chore.

Examples:

feat: add support for multiple blueprints
fix: correct region validation in init command
chore: update dependencies

Remove the AWS luminarlz CLI

For whatever reason you want to remove the dependency to the AWS luminarlz CLI you can do so. After calling:

npm run cli -- synth

You find the raw aws-accelerator-config in the aws-accelerator-config.out directory and deploy it with any other mechanism you like.