Technical FAQ
Technical questions, answered from the repositories and the contributor rules of each Baseline edition. Deployment procedures are in each edition's documentation set; this page explains how the repositories behave.
What tools and versions do I need?
Every edition pins OpenTofu 1.12.6, Terragrunt 1.1.6 and tflint 0.64.0 in root.hcl and the workflows; use the same versions locally. Python runs the guard scripts, and pre-commit runs them before each commit. The providers and rulesets differ per edition:
| Edition | Providers | tflint ruleset |
|---|---|---|
| AWS Enterprise Baseline | hashicorp/aws ~> 6.65 | AWS ruleset 0.48.0 |
| Azure Enterprise Baseline | hashicorp/azurerm ~> 5.7, hashicorp/azuread ~> 3.10, Azure/azapi ~> 2.13 | tflint-ruleset-azurerm 0.32.0 |
| GCP Enterprise Baseline | hashicorp/google and google-beta ~> 8.5 | tflint-ruleset-google 0.40.0 |
The Azure and GCP repositories also pin Checkov 3.3.19 and use no registry modules. The full tables are on the release notes page and the versions pages of the Azure and GCP editions.
How do I customize the repositories for my organization?
Search for the tags. git grep "TODO: " lists every value that must be set (namespace, domain, emails, the GitHub organization, group IDs, CI secrets, and the tenant or organization ID); git grep "@optional: " lists every choice that may be changed (feature switches, compliance options, sizing, cost-bearing options). The namespace acme, the domain company.com and the home region are each set in one place, common.hcl: us-west-2 in the AWS edition, eastus2 in the Azure edition, us-west1 in the GCP edition. In every deployment option, BuiltForProd's team does this customization for you.
How do I add a region?
In every edition a region exists for the code when its folders exist: environments/<group>/<unit>/<region>/ with a region.hcl that declares only the region slug (the folder name is the region) and a terragrunt.stack.hcl listing the region's units, plus the region's block in the address plan. The address plan already reserves space: sixteen regions in the organization's /8.
- AWS Enterprise Baseline. Add the region to the VPC map and re-apply the
ipamunit, which discovers the new region from the tree; the region-restriction policy picks it up the same way. - Azure Enterprise Baseline. The
ipamunit publishes ranges only for regions with folders, the region-restriction initiative computes its allowed locations from the same folders, and the region gets its ownenvironments/core/network/<region>/network.hcl.centralusis reserved invnet_map.yaml. - GCP Enterprise Baseline. The VPCs are global, so the region adds subnets and a Cloud NAT per VPC, and
gcp.resourceLocationswidens to the new region in the same plan.us-east1is reserved innetwork_map.yaml.
How do I add a stage?
A workload stage is data in every edition: an entry in the map of the organizations unit, a folder whose stack file instantiates the edition's stage template, a block in the address plan, and a place in exactly one isolation domain in network.hcl. The blueprints then add the stage to their configuration, CI matrices and GitHub Environments. The address plan reserves eight workload stages per region.
- AWS Enterprise Baseline. An account with its root email, an
account.hcland a stack file that instantiatesstacks/plat-account; Identity Center assignments for the stage. - Azure Enterprise Baseline. An entry in
plat_subscriptions(created from the billing scope or adopted), a stack file that instantiatesstacks/plat-subscription, the stage DNS zone and the blueprint deployer scope. - GCP Enterprise Baseline. An entry in
plat_projects(project IDacme-plat-<name>), a stack file that instantiatesstacks/plat-project, and the stage in the units that create one resource per stage (DNS zones, SOPS keys, access groups).
Where is state, and how are keys named?
Every edition keeps the state of the Baseline and both infrastructure blueprints in one store in the root unit, with one state object per unit. The key is the unit's generated path with the .terragrunt-stack/ segments removed, so it is the same whether a stack file lists the unit directly or a template generates it; the blueprints write under apps/app-blueprint/ and apps/etl-blueprint/. See Terragrunt units and stacks.
- AWS Enterprise Baseline. The S3 bucket
acme-use1-root-tfstatein the management account inus-east-1: versioned, KMS-encrypted, TLS-only, native locking. - Azure Enterprise Baseline. The storage account
stacmeeus2roottfstate, containertfstate, inacme-core-root: Entra ID access only, blob-lease locking, versioning, 90-day soft delete; each blueprint identity may write only its own prefix. - GCP Enterprise Baseline. The bucket
acme-usw1-root-tfstateinacme-core-root: native locking, versioning, 7-day soft delete; only the Baseline and the two infrastructure blueprints may write, each to its own prefix.
Where do I run Terragrunt from?
From a folder that holds a terragrunt.stack.hcl (terragrunt stack run plan, terragrunt stack output, terragrunt stack clean) or from the repository root with --working-dir environments. Never from the repository root without it: Terragrunt would treat units/ and stacks/ as live configuration and generate into them.
Can I plan an environment before anything exists?
Yes, in every edition. Every dependency in every unit declares mock outputs allowed for validate and plan, so a brand-new environment plans end to end, and apply always uses real outputs. Units whose providers must reach a live resource need the real dependency first: on AWS the EKS add-on units and Fluent Bit's cluster lookup, and the web platform's shared-infra/eks units call get_aws_account_id() and need credentials to render even offline; on Azure the ingress controller unit, which needs the cluster's custom resource definitions at plan time.
Why did my change to one unit plan changes in four stages?
Because a unit definition is shared. The stage template (plat-account, plat-subscription or plat-project) is instantiated by all four workload stages, so one edit to a unit it lists affects all four; the required-inputs guard renders every generated unit for that reason. Per-stage differences belong in the stack file's values, not in the definition.
How do the blueprints get network IDs and subnets from the landing zone?
Through a published contract, never through another repository's state. The Baseline writes the values each stage needs, and the blueprints read them at plan time and publish their own outputs the same way; the landing-zone contract page explains the pattern.
- AWS Enterprise Baseline. The
ssm-publishunit writes SSM Parameter Store parameters such as/acme/usw2/<stage>/vpc/{id,cidr,private_subnet_ids,public_subnet_ids},/tgw/attachment_idand/account/idper workload account. - Azure Enterprise Baseline. The
kv-publishunit writes 30 secrets named<area>--<name>, such asvnet--subnet--aks, to the contract vaultkv-acme-eus2-<stage>-platof each stage. - GCP Enterprise Baseline. The
pm-publishunit writes 24 Parameter Manager parameters named<service>--<key>, such asvpc--subnet--proxy, in each plat project.
Why does a workload role get AccessDenied on EBS or KMS (AWS)?
In the AWS edition, the MFA statement of the guardrail policy denies roles that are neither acme-* nor tagged mfa-exempt = true. Name IAM roles for workloads within the namespace or add the tag.
How do I upgrade OpenTofu, a provider or a module?
Change the pin in root.hcl (and every module versions.tf the guard lists), plan in dev, then staging, then prod, and revert the pin to roll back. Major versions are high risk and need the upgrade guide read first. The versioning policy has the risk matrix; the procedures are indexed under upgrade guides.
Can I switch address plans later?
Not without a rebuild. The AWS edition ships eks_vpc_map.yaml and non_eks_vpc_map.yaml, and the Azure edition vnet_map.yaml and vnet_map_compact.yaml; every CIDR differs between the two maps of an edition, so switching destroys and recreates every network, subnet and route. The choice is made once, before the first deployment. The GCP edition ships one map, network_map.yaml.
Do the repositories use Kubernetes for everything?
No. The AWS landing zone runs no Kubernetes at all, the Azure edition's CI runners are a Container Apps job, and the GCP edition's optional CI runners run on GKE Autopilot. The web platform runs on EKS, AKS or GKE; the ETL platform runs on Glue with a Lambda trigger, on Azure Databricks with a Container Apps job trigger, or on Dataproc Serverless with a Cloud Run trigger. The brand note is explicit that BuiltForProd is not a Kubernetes company; the general FAQ covers positioning.