Upgrade guides
Every Baseline edition has procedures that keep a running deployment current, from changing a version pin to switching a network or security feature on or off. This page indexes those procedures so you know which one applies. The step-by-step guides themselves, with expected plan output, verification commands and rollback, are in each edition's documentation set (AWS, Azure, GCP), available to customers who hold that edition.
Routine updates
| Procedure | Applies when | Risk | Rollback |
|---|---|---|---|
| OpenTofu or Terragrunt version update | A new tool release | Medium | Revert the version constraint in root.hcl |
| Cloud provider version update | A new release of hashicorp/aws; azurerm, azuread or azapi; google and google-beta | Medium | Revert root.hcl and the module versions.tf files |
| Registry module version update (AWS) | A new release of vpc, eks, lambda and the others | High for a major, low for a patch | Revert the version pin |
| GitHub Actions SHA update | A new release of an action | Low | Revert the SHA in the workflow file |
Each follows the same path: change the pin in its one place, plan in dev and look for replacements, open the pull request, let CI plan with the new version, merge, and let staging and prod follow. The approvals per risk level are in the versioning policy.
Taking upstream changes into your fork
Your repositories are forks of BuiltForProd's. There are two ways to see what changed upstream since your last sync: a two-dot comparison URL in GitHub between the upstream commit and yours, or git fetch upstream followed by git log HEAD..upstream/main and git diff HEAD..upstream/main after adding the upstream remote. Merging is done on a branch (chore/update-from-upstream), never directly into main, so that your plan workflow verifies the upstream changes against your customized infrastructure before they merge. Conflicts in files you customized are resolved by hand.
AWS edition runbooks for switches
Some switches change a running landing zone in a way that one unattended apply would get wrong. Each has a runbook that says what the apply does to the running environment, the order of operations, expected plan output and verification.
| Runbook | Applies when | What it does to the running environment |
|---|---|---|
| Enabling or disabling Network Firewall egress inspection | Switches enable_network_firewall | Four applies back to back; spoke egress pauses for a few minutes; costs about $865 per month for three AZs plus $0.065 per GB when on |
| Enabling Transit Gateway peering for a second region | Switches enable_tgw_peering in a non-home region | One apply from the second region peers both gateways and installs static routes in both; about $36 per month per peering plus inter-region transfer |
| Moving a stage between isolation domains | Changes isolation_domains in network.hcl | Re-applies the Transit Gateway route tables; each re-associated spoke loses Transit Gateway connectivity for a few seconds |
| Rolling the ETL Lambda image forward or back | A release must be redeployed or reverted | Re-runs the release workflow for the wanted tag, which rewrites the SSM image-tag parameter; nothing is edited by hand |
Enabling a security service (security.hcl) | Switches GuardDuty, Security Hub, Inspector or Macie on or off | Three steps per service in a fixed order across the management and security accounts, then a second pull request for organization auto-enrollment |
| Changing the Terragrunt Stacks layout | Moves units between stack files or introduces a template | Nothing moves when the renders are identical; state keys stay equal to the folder paths. Documents the day-to-day commands and the run report |
Verifying that a change is layout-only
Before merging a change that should not alter any resource, render every generated unit before and after (terragrunt render --format json in each generated unit folder, or terragrunt run --all render --format json) and compare the inputs, generated files, resolved dependency paths and the remote-state key. Identical renders mean identical plans.
Getting help with an upgrade
Under BuiltForProd Managed, BuiltForProd DevOps engineers provide consultation and support for the platform they delivered, upgrades included; the support FAQ explains what each option includes.