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. Search for open TODO comments in the generated files and adapt them to your needs.

Other CLI commands

Documentation for the other CLI commands can be found in the README generated when intializing a new AWS landing zone. Have a look at the foundational blueprint README.

LZA Core CLI

Some of the CLI commands are using the LZA Core CLI underneath.

Running the LZA core CLI currently requires a local checkout of the LZA repository and building the project which will take a moment.

This will be done automatically for you once and every time you update the LZA version.

You should add /.landing-zone-accelerator-on-aws-* to your .gitignore file so that these local LZA checkouts are not committed to your repository.

Development

Prerequisites

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

yarn projen

• To run the CLI without building it:

./src/index.ts

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.