Getting Started

Contents

• Getting Started
• Assumptions
• Project Structure
  • .metastructure.yml
  • Project Config File
  • license-checker-config.json

Getting Started

Metastructure is a Node.js package, so you'll need to have Node.js installed on your system. You can download it here or MUCH better use NVM.

Metastructure expects your Terraform project to be embedded in an NPM package. For best results, just clone the Metastructure Template Repo!

If you like, you can install Metastructure as a dev dependency:

npm i -D metastructure

... in which case you would run it like npx metastructure.... That's what you will see in the Metastructure Template Repo.

Otherwise, you'll want to install it as a global dependency:

npm i -g metastructure

Assumptions

Metastructure assumes you are building an AWS Organization secured by IAM Identity Center single sign-on (SSO). You CAN do other things—in fact you HAVE to, to bootstrap a project—but in the long term, you shouldn't.

If you build your project according to the AWS Well-Architected Framework, then Metastructure will serve you well.

Project Structure

Metastructure is agnostic about your project structure, with these exceptions...

.metastructure.yml

Note the dot at the beginning of the filename.

This file must be located in your project root. It contains a single YAML object that looks like this:

configPath: src/metastructure.yml

The purpose of this file is to tell Metastructure where to find your project configuration file, which you can name whatever you like and put wherever you want. The path is relative to the project root, and doesn't even have to be in the same project!

For example, to support testing the Metastructure repo has a .metastructure.yml file that points to a config file in the Metastructure Template Repo.

When you run Metastructure, it looks for a .metastructure.yml file in the current directory's project root, which points to a config file as described above. All subsequent activity will take place in that config file's project directory.

If your project doesn't have a .metastructure.yml file, you can specify your config file location at the command line using the -c or --config-path flag. If you do neither, Metastructure will be unable to locate your project config file and will throw an error.

Project Config File

As described above, .metastructure.yml points to a project config file, which can have any name you like and may not even be in the same project.

The structure of this file is laid out on the Metastructure Config page. Any file paths contaned in this file should be relative to its own project root.

license-checker-config.json

PCI and other compliance standards require that all code files contain a licensing header.

Metastructure is optionally integrated with the license-check-and-add package, which will place a licensing header as a properly-formatted comment at the top of each generated file (in fact all non-excluded files in your project directory).

If you choose to use this feature, place a license-checker-config.json file in your project root and point it at a license file somewhere in your project.

This package is a little quirky, particularly in how it processes ignore patterns, but it's the best solution I've found that supports configurably managing license headers across multiple file formats. If you have a better idea, please share!

See the Metastructure Template Repo for a working example.