Versioning policy
Every third-party input to the platform is pinned to an exact version in one known place, and every pin is changed on its own, planned in dev before staging and prod, with a risk level and an approver that depend on the kind of change. This policy is what the update lifecycle document delivered with the Baseline prescribes; the current pins are on the release notes page.
Where each kind of pin lives
| Kind | Pin | One place |
|---|---|---|
| OpenTofu | Exact in CI (TF_VERSION), range in root.hcl (>= 1.12.6, < 2.0.0) | root.hcl and the workflows of each repository |
| Terragrunt | Exact in CI (TG_VERSION), minimum in root.hcl (>= 1.1.5) | Same |
| AWS provider | ~> 6.65 | root.hcl generates versions.tf into every unit; a module ships its own versions.tf only for provider aliases or extra providers, repeating the pin exactly |
Other providers (helm, kubernetes) | Version constraint | The module versions.tf files that declare them |
| Registry modules | Exact (?version=6.7.3) | The unit definition (landing-zone VPC and Transit Gateway) or the module main.tf |
| GitHub Actions | Commit SHA, version in the trailing comment | Every workflow file |
| SOPS, tflint and its ruleset | Exact | The secrets workflows; plan.yml and .tflint.hcl |
| Container images | Immutable tags, main-<sha> and vX.Y.Z | ECR; see immutable artifacts |
scripts/check-module-versions.py fails in pre-commit and CI when a module declares required_providers it should not, or repeats the root pins incorrectly. Registry module upgrades are their own change with a plan review; a provider upgrade changes root.hcl and every module versions.tf the guard lists in the same change.
Risk and approval per change
| Change | Risk | Testing | Approval |
|---|---|---|---|
| Patch version (x.y.Z) | Low | Dev only | Team Lead |
| Minor version (x.Y.z) | Medium | Dev and staging | DevOps Lead |
| Major version (X.y.z) | High | Dev, staging and a canary | Platform Lead and DevOps Lead |
| Provider major | High | Full chain | Platform Lead |
| New module introduction | Medium | Dev and staging | Platform Lead |
| Self-hosted runner module update | Medium | A disposable workflow | DevOps Lead |
Per component, the update lifecycle rates OpenTofu and Terragrunt updates and AWS provider updates as medium risk, registry module updates as high risk for a major version and low for a patch, and GitHub Actions SHA updates as low risk. Major module versions (for example EKS 20.x to 21.x) often include breaking changes: the upgrade guide is read and dev is tested first.
The update path
- Install the new version locally where the change is a tool.
- Change the pin in its one place (and, for OpenTofu and Terragrunt,
TF_VERSION/TG_VERSIONin every workflow of the repository; for the AWS provider, the moduleversions.tffiles the guard lists). - Plan in dev from the stage or account folder and look for resource replacements. A single unit is planned with
terragrunt run --all plan --filter '**/<unit>'. - Open the pull request; CI plans with the new version and posts the plan.
- After merge, the apply workflow runs: in the Baseline as one job under the
prodGitHub Environment, in the blueprint infrastructure repositories as adev,stagingandprodmatrix, each job under the Environment of its stage.
Rollback is reverting the pin: the version constraint in root.hcl, the module version, or the action SHA.
Monitoring after an update
| Check | How | When |
|---|---|---|
| No unexpected drift | The drift detection workflow | Next scheduled run |
| Resources healthy | CloudWatch metrics and alarms | One hour after apply |
| CI still works | The next pull request pipeline | After merge |
Repository versions and upstream updates
Each repository carries a version in its README (currently 1.0.0). Customer repositories are forks; the update lifecycle explains how to compare a fork with the upstream repository and how to merge upstream changes on a branch so that the fork's own plan workflow verifies them first. Changes that touch already-applied deployments come with a runbook; they are indexed under upgrade guides.