The getting started guide ends once you have a fully configured AWS organization, one that should last you many years and weather all sorts of growth in infrastructure and team size. This manual exists to orient you within that organization so you know what you have and how to use it most effectively to achieve your company's goals.

This is a distillation of the Substrate design that better aligns with the rest of the manual and omits all the aspirational parts. Please use inline comments, Slack, or [email protected] to ask questions.

Your Substrate directory

In the getting started guide, you decided on a directory where you'll run Substrate commands and started committing all the files Substrate places there to version control. This directory is a critical part of your Substrate-managed AWS organization and should be managed like source code.

The substrate.* files in this directory are records of how you responded to the various prompts from Substrate commands. While it's possible to edit a file and re-run the corresponding Substrate commands, it's recommended to edit the files when offered the opportunity to do so by the Substrate commands themselves.

The Terraform modules placed in the modules subdirectory - intranet, lambda-function, and substrate - are generated and kept up-to-date by Substrate commands. They're copied here to ensure you completely control your Substrate-managed AWS organization even if you decide to stop using Substrate and continue on your own.

The root Terraform modules - every leaf directory in the root-modules subdirectory tree are where you run Terraform commands. Each has a Makefile to enable single command directory change and Terraform invocation thus: make -C root-modules/example/staging/alpha apply

AWS accounts

Why even bother having more than one AWS account, anyway?

• Security: The AWS IAM team recommends using AWS accounts as the primary security boundary between unrelated systems. Within a single account it can be difficult to fully model permissions and convince oneself that two systems really are separate. Between multiple accounts, though, it's far easier to move quickly by granting broad permissions within one account with confidence that those permissions don't bleed over into the other accounts.
• Cost management: Most organizations struggle to tag AWS resources effectively enough to get a clear picture of where they're spending money. Every single AWS resource, though, is unavoidably attached to some account number. By mapping AWS accounts to cost centers, one can get a baseline picture of costs that's often enough all by itself.

Substrate wholeheartedly endorses the use of multiple AWS accounts. There are a few special AWS accounts in a Substrate-managed AWS organization and then as many more as you like for your purposes.

The special accounts are:

• The master account, which contains no resources and is only used to create and control other accounts within the organization.
• The audit account, which hosts CloudTrail logs for the entire organization.
• The deploy account, which hosts deployable artifacts for exchange between all domains, environments, and qualities in order to allow them to remain otherwise completely separate.
• The network account, which hosts VPCs and subnets that are shared with other accounts to simplify network topology and reduce network transfer costs.

There are additionally admin accounts (of which there can be more than one), which host intranet services like the credential and instance factories that can exchange IdP (Google or Okta) credentials for temporary AWS credentials or EC2 instances.

Finally, there are accounts where you host your software (be it software you've written yourself or an AWS-managed service). Each of these accounts is tagged with a domain, environment, and quality.

Domains, environments, and qualities