Substrate documentation

New to Substrate? Here’s the deal: In AWS, the one true unit of isolation is the AWS account but isolating all your environments and services in their own AWS accounts can be tedious. Substrate removes all the hassles that come with having lots of AWS accounts - access, navigation, IAM roles and permissions, networking, and more - so you can reap all the security, reliability, and compliance benefits of true isolation between your AWS workloads.

If you’re the first person at your company to pick up Substrate, begin by bootstrapping your AWS organization.

New users at companies already using Substrate can jump straight to getting started with Substrate and learn about the daily workflow Substrate encourages.

Once you’re up and running, this site has all your references for common access and management tasks, resources for your first (or fourteenth) SOC 2 audit, architectures that get the most of of Substrate and AWS, and more.

This Documentation is also available on the GitHub, so feel free to open an issue or a pull request if you find any problems or want to suggest improvements.

Table of contents

• Release notes

Bootstrapping your Substrate-managed AWS organization

• Overview
• Opening a fresh AWS account
• Installing Substrate and Terraform
• Configuring Substrate shell completion
• Bootstrapping your Substrate-managed AWS organization
• Integrating your identity provider to control access to AWS
  • Integrating your Azure AD identity provider
  • Integrating your Google identity provider
  • Integrating your Okta identity provider
• Finishing up in your management account
• Configuring CloudTrail
• Integrating your original AWS account(s)

Using Substrate

• Getting started (after someone else has bootstrapped Substrate)
• Daily workflow
• Upgrading Substrate
• Upgrading Terraform

Accessing and navigating AWS

• Accessing AWS in your terminal
• Accessing the AWS Console
• Moving between AWS accounts
• Using AWS CLI profiles
• Jumping into private networks
• Enumerating all your AWS accounts
• Enumerating all your root Terraform modules
• Enumerating all your custom AWS IAM roles
• Cost management
• Deep-linking into the AWS Console

Managing AWS accounts, roles, and resources

• Managing your infrastructure in service accounts
• Adding a domain
• Adding an environment or quality
• Adding custom IAM roles for humans or services
• Onboarding users
• Offboarding users
• Allowing third parties to access your AWS organization
• Adding administrators to your AWS organization
• Subscribing to AWS support plans
• Removing an AWS account from your organization
• Closing an AWS account
• Adding an AWS region
• Removing an AWS region
• Using Amazon EC2 when IMDSv2 is required
• Customizing EC2 instances from the Instance Factory
• Writing Terraform code
• Additional Terraform providers
• Deploying software
• Protecting internal tools

Compliance

• Addressing SOC 2 criteria with Substrate
• Auditing your Substrate-managed AWS organization

Architectural reference

• Accounts in a Substrate-managed AWS organization
• Diagram of a Substrate-managed AWS organization
• Domains, environments, and qualities
• Global and regional Terraform modules
• Root Terraform modules
• Substrate filesystem hierarchy
• Networking
• Diagram of a multi-quality, multi-region service
• Multi-region strategy
• Technology choices
• Multi-tenancy
• Deciding where to host internal tools
• Telemetry in Substrate
• Changes to Substrate commands in 2024.01

Runbooks for emergency and once-in-a-blue-moon operations

• Changing identity providers
• Sharing CloudWatch data between accounts
• Regaining access in case the Credential and Instance Factories are broken
• Debugging Substrate
• AWS IAM Identity Center

Meta

• Typographical conventions