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 is the BuiltForProd policy for the repositories of every Baseline edition and its blueprints; 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.6) | Same |
| Cloud providers | hashicorp/aws ~> 6.65; hashicorp/azurerm ~> 5.7, hashicorp/azuread ~> 3.10, Azure/azapi ~> 2.13; hashicorp/google and google-beta ~> 8.5 | 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 | Version constraint (helm, kubernetes, time, random, databricks) | The root.hcl or module versions.tf files that declare them |
| Registry modules (AWS) | Exact (?version=6.7.3) | The unit definition (landing-zone VPC and Transit Gateway) or the module main.tf; the Azure and GCP repositories use no registry modules |
| 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 (the AWS, azurerm or google ruleset) |
| Container images | Immutable tags, main-<sha> and vX.Y.Z | ECR, Azure Container Registry or Artifact Registry; 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, OpenTofu and Terragrunt updates and cloud provider updates are medium risk, registry module updates high risk for a major version and low for a patch, and GitHub Actions SHA updates low risk. Major registry module versions on the AWS edition (for example EKS 20.x to 21.x) often include breaking changes, and so do major provider versions: 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 and the versions in the runner image where the repository builds one; for a provider, the moduleversions.tffiles the guard lists). - Plan in dev from the stage 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 | The edition's monitoring and alerts (CloudWatch, Azure Monitor, Cloud Monitoring) | One hour after apply |
| CI still works | The next pull request pipeline | After merge |
Repository versions and upstream updates
Each infrastructure and code repository carries a version in its README (currently 1.0.0). Customer repositories are forks; a fork is compared with the upstream repository and upstream changes are merged on a branch, so that the fork's own plan workflow verifies them first. Switches that change a running deployment in a fixed order come with a runbook; they are indexed under upgrade guides.