Skip to main content

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​

ProcedureApplies whenRiskRollback
OpenTofu or Terragrunt version updateA new tool releaseMediumRevert the version constraint in root.hcl
Cloud provider version updateA new release of hashicorp/aws; azurerm, azuread or azapi; google and google-betaMediumRevert root.hcl and the module versions.tf files
Registry module version update (AWS)A new release of vpc, eks, lambda and the othersHigh for a major, low for a patchRevert the version pin
GitHub Actions SHA updateA new release of an actionLowRevert 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.

RunbookApplies whenWhat it does to the running environment
Enabling or disabling Network Firewall egress inspectionSwitches enable_network_firewallFour 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 regionSwitches enable_tgw_peering in a non-home regionOne 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 domainsChanges isolation_domains in network.hclRe-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 backA release must be redeployed or revertedRe-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 offThree 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 layoutMoves units between stack files or introduces a templateNothing 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.