Upgrade guides
The update lifecycle document delivered with the Baseline holds every upgrade procedure, from changing a version pin to migrating an already-applied deployment across a layout change. 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 the AWS Baseline documentation set, available to Baseline customers.
Routine updates
| Procedure | Applies when | Risk | Rollback |
|---|---|---|---|
| OpenTofu or Terragrunt version update | A new tool release | Medium | Revert the version constraint in root.hcl |
| AWS provider version update | A new provider release | Medium | Revert root.hcl |
| Registry module version update | 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. The update lifecycle explains 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.
Runbooks for already-applied deployments
Some upstream changes alter units that are already deployed. Each has a runbook that says when it applies, what the apply does to a live environment, the order of operations, expected plan output and verification. Fresh deployments need none of them.
| Runbook | Read it before merging an update that | What it does to a live deployment |
|---|---|---|
Moved units (global/ folders) | Introduces global/ folders into an applied landing zone | Copies nine state objects (plus the runner VPC, if applied under its old name) to their new keys while the apply workflow is paused; the Client VPN security group is replaced if the endpoint is enabled |
| Isolation-domain Transit Gateway route tables | Introduces network.hcl and isolation_domains | Applies the hub VPC, the Transit Gateway and the route tables in order; every spoke loses Transit Gateway connectivity for a few seconds while its association moves |
| 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 |
| 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 carries old per-unit values into the file | Three steps per service in a fixed order across the management and security accounts, then a second pull request for organization auto-enrollment |
| Adopting the Terragrunt Stacks layout | Introduces units/ and stacks/ | Nothing to migrate; state keys are unchanged by construction. Documents the day-to-day commands and the run report |
The layouts each runbook replaces are summarized under deprecation notices.
Verifying that a change is layout-only
Before merging a change that should not alter any resource, the update lifecycle prescribes rendering every generated unit before and after (terragrunt render --format json in each generated unit folder, or terragrunt run --all render --format json) and comparing inputs, generated files, resolved dependency paths and the remote-state key. Identical renders mean identical plans. This is how the Stacks migration itself was verified.
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 tier includes.