Setting Up Your Dev Environment

Contents

• Setting Up Your Dev Environment
• Project Scripts
  • license
  • release
• Template vs Project Mode
  • Config & CLI Overrides
  • Config Updates
  • Gitignored Files

Setting Up Your Dev Environment

This guide is intended to get you up and running with the Metastructure Template Repo in your local development environment. It assumes you have a basic understanding of the tools involved and are comfortable with the command line.

The assumption is that you will be working in Visual Studio Code. This is not a hard requirement, but the template contains a set of recommended VS Code extensions that will make your life easier if you use them.

Every platform is different. I'm working in Windows, but have tried to make these instructions as platform-agnostic as possible. If you run into trouble, please open a discussion.

To get started, install the following tools:

• Git

• Terraform

• TFLint

• AWS CLI

• Node.js (v20 LTS) or MUCH BETTER install it with NVM!

• Visual Studio Code

Once you've got all this installed, clone the Metastructure Template Repo & open it in VS Code.

If you're just exploring Metastructure, a local clone is fine. If you're building your own infrastructure, you'll be better off creating a new repo using the Metastructure Template Repo as a template. And if you'd like to develop new patters WITHIN the Metastructure Template Repo, fork it!

VS Code will ask you if you'd like to install recommended extensions. Do so. If you miss this step, you can install them manually by clicking on the Extensions icon in the sidebar and searching for "Recommended".

Run the following commands to install package dependencies & git hooks:

npm i
npx lefthook install

Metastructure is included as a dev dependency in this package, so you can run it with npx metastructure. To save yourself a few keystrokes, install it globally with:

npm i -g metastructure

For the sake of simplicity, we'll assume you have done that. Now run this command:

metastructure -w bootstrap -g

You should see an output in your console that looks something like this:

Workspace: bootstrap

Parsing config file... Done!

Generator Params
assume_role:     'OrganizationAccountAccessRole'
aws_profile:     'META-BOOTSTRAP'
use_local_state: true
workspace:       'bootstrap'

Generating workspace 'bootstrap'...
Generating src/bootstrap/_accounts.tf... Done!
Generating src/bootstrap/_backend.tf... Done!
Generating src/bootstrap/_outputs.tf... Done!
Generating src/bootstrap/_providers.tf... Done!
Generating src/bootstrap/_shared_config.local... Done!
Generating src/bootstrap/_s3_access_logs.tf... Done!
Generating src/bootstrap/_sso.tf... Done!
Generating src/bootstrap/_terraform.tf... Done!
Generating src/modules/global/_outputs.tf... Done!
Done!

Applying license headers...
Done!

Formatting files...
src\bootstrap\_accounts.tf
src\bootstrap\_backend.tf
src\bootstrap\_outputs.tf
src\bootstrap\_providers.tf
src\bootstrap\_s3_access_logs.tf
src\bootstrap\_sso.tf
src\modules\global\_outputs.tf
Done!

If you see this output, congratulations! You've just generated your bootstrap workspace files!

If you run into any trouble, please open a discussion.

Otherwise, move on to Hello, Enterprise! and follow the instructions to stand up your AWS Organization!

Project Scripts

TODO

license

TODO

release

TODO

Template vs Project Mode

The Metastructure Template Repo has to play two somewhat different roles:

• It is a TEMPLATE under continuous development.

• Once you adopt this template, it becomes your PROJECT, and has slightly different requirements.

Config & CLI Overrides

In TEMPLATE mode, the project config needs to remain stable unless we make changes to the template itself. Metastructure supports local project config overrides and workspace CLI overrides so we can test different configurations without persisting those values back to the template repo.

In PROJECT mode, the workspace CLI overrides can still be handy, but you MIGHT want to persist them back to the repo (just remove the local token from the file name and update workspaces.<workspace>.cli_defaults in your project config). The local project config overrides are no longer necessary... in fact, you should NOT use them, since all of your developers should be working from the same project config!

Config Updates

In TEMPLATE mode, while conducting tests against AWS you will generate Terraform outputs that must be merged with your project configuration. Since you don't want to pollute the template with these values, you should direct these updates to your local project config override using Metastructure's -o or --update-override flag.

In PROJECT mode, you want to update your project config directly so your terraform outputs will be persisted to your project repository. In this case, use the -u or --update-config flag.

See Config Override Updates for more info.

Gitignored Files

In TEMPLATE mode, add the following .gitignore file to the src directory to prevent itself and any generated code from persisting to the remote repo, since these files would persist values from our local test configurations:

src/.gitignore

.gitignore
_*
_*.*

In PROJECT mode, you DEFINITELY want to persist generated code to your repo. Version control is your first line of defense against regressions: if your generated contains unexpected changes, you know you have a problem! So once you enter PROJECT mode, you should remove the src/.gitignore file.