Skip to main content

Key concepts

Ten ideas carry the rest of this documentation. Each gets a paragraph here and a full page in the concepts section or the glossary.

How the pieces nest​

Landing zone​

A landing zone is the multi-account foundation every application runs on: the AWS Organization and its accounts, the network that connects them, the security and compliance services that watch them, identity and access for people and pipelines, and the state and delivery machinery that manages all of it. The BuiltForProd AWS Baseline is a landing zone, held in one repository. Application teams do not work in it; they build on what it publishes. Read landing zones.

Account​

An AWS account is the hard boundary for IAM, billing and blast radius. The Baseline creates a management account plus 13 member accounts in two organizational units (OUs): core holds shared, single-purpose accounts (security, audit, identity, network, dns, artifacts, auto, corp, public) and plat holds one workload account per stage (sandbox, dev, staging, prod). Every account receives the same account baseline: default EBS encryption, an account-wide S3 public-access block, AWS Config recording and the deployer role CI uses. The architecture overview draws all 14.

Unit​

A unit is one deployable module instance with one state file: a VPC, a Transit Gateway attachment, a GuardDuty detector. Its definition lives once in units/<unit>/terragrunt.hcl and says which module to use, which dependencies it reads and which inputs it passes. Per-instance data arrives as values. The same definition serves every account or stage that lists it. Read Terragrunt units and stacks.

Stack​

A stack file, terragrunt.stack.hcl, sits in a region or global folder and lists which units that folder deploys, with their values. Repeated sets are templates under stacks/: plat-account holds the seven units every platform account has, webapp-stage the sixteen units of a web application stage, etl-stage the six of a data stage. Terragrunt generates the units into a git-ignored .terragrunt-stack/ tree; nothing under environments/ is hand-written unit code. Read Terragrunt units and stacks.

Blueprint​

A blueprint is an opinionated, production-ready reference architecture for a real workload, delivered as its own repositories and deployed into the platform accounts. Three exist: the Web App Blueprint (EKS, ArgoCD, DocumentDB, ElastiCache, CloudFront, with application code and a GitOps repository), the Data and ETL Blueprint (S3 data lake, Glue, Lake Formation, Lambda) and the Secrets Blueprint (SOPS and KMS to SSM Parameter Store). A blueprint never creates what the landing zone owns; it reads VPC ids, subnet ids, account ids and Transit Gateway attachment ids from SSM Parameter Store. Read the blueprints.

Entitlement​

An entitlement is the product your organization holds, and it decides which documentation sets you can open. The Platform set is public. The AWS Baseline set and each blueprint set show their overview to everyone and the rest to organizations entitled to that product. Entitlements are stored on your organization by BuiltForProd staff; you see them after signing in. Read how to use these docs.

Environment​

In the Baseline, an environment is a region slug: usw2 for us-west-2, glob for the global folders that hold organization-wide singletons such as IAM, Organizations, public DNS zones, IPAM and the Client VPN endpoint. A stage is the workload account's role: sbx, dev, stg, prd. Resource names combine namespace, environment and stage: acme-usw2-prd-vpc. Read environments and promotion.

Promotion​

Promotion moves a change from dev through staging to prod without rebuilding it. Infrastructure merges to main and applies: the blueprint infrastructure repositories run a dev, staging and prod matrix whose prod job waits for the prod GitHub Environment, and the Baseline applies in one job under the prod Environment. Application images are built once, tagged immutably as main-<short sha>, given a vX.Y.Z tag at release, and never rebuilt for a later stage. Rollback is a Git revert or a promotion of the previous tag. Read environments and promotion.

GitOps​

GitOps means the desired state of a system lives in Git and a controller reconciles the running system to it. In the Web App Blueprint, ArgoCD reads the Helm chart and per-stage values from the GitOps repository. No pipeline pushes to that repository directly: the application repository opens a pull request per rollout, dev and staging merge themselves, prod is merged by a person and synced manually. Read GitOps.

Placeholder values​

The repositories are templates. Every value that must be set per deployment carries a TODO: comment and every optional choice an @optional: comment, so git grep lists both. This site follows the same idea: acme is the namespace, ACME the SSO group prefix, company.com the primary domain, us-west-2 the home region, and 111111111111 through 151515151515 the fourteen account ids. Signed-in readers whose organization profile is filled in see their own values in place of the samples. Read how to use these docs.

Where these ideas come from​

The vocabulary is the one the repositories use. The contributor rules define unit, unit definition, stack file, template, values and generated tree exactly as above, and the checks in every repository enforce them: a stack file beside every region.hcl, no hand-written unit under environments/, every definition referenced, every dependency mocked so a new environment can be planned end to end before anything exists. The infrastructure as code page explains why that discipline matters.