OpenTofu and Terraform
Every edition of the BuiltForProd Baseline is built on OpenTofu and Terragrunt. OpenTofu is the open-source, Terraform-compatible engine that plans and applies the modules; Terragrunt is the layer above it that generates the units, the provider configuration and the state backend. The word "Terraform" still appears in file names and a few resource names because the language and the ecosystem are shared.
Why it matters in production
The engine that changes your infrastructure must be predictable. Every engineer and every pipeline has to run the same version, or a plan on one machine will not match the apply on another and a state file written by a newer version cannot be read by an older one. Open source matters for the same reason: the tool that holds your infrastructure definition should not be able to change its terms under you.
How each edition implements it
One place for every version
The rule is the same in every infrastructure repository of every edition. root.hcl is the only place OpenTofu and the cloud providers are pinned. It generates a versions.tf into every unit (if_exists = "skip", so a module that ships its own is kept) and a provider.tf with the provider configuration (always overwritten). The AWS Enterprise Baseline's pins look like this:
terraform_version_constraint = ">= 1.12.6, < 2.0.0"
terragrunt_version_constraint = ">= 1.1.6"
generate "versions" {
path = "versions.tf"
if_exists = "skip"
contents = <<-EOF
terraform {
required_version = ">= 1.12.6"
required_providers {
aws = {
source = "hashicorp/aws"
version = "~> 6.65"
}
}
}
EOF
}
CI pins exact versions in every workflow: OpenTofu 1.12.6 and Terragrunt 1.1.6 as TF_VERSION and TG_VERSION. A module ships its own versions.tf only when it uses a provider alias or a provider root.hcl does not pin, and then repeats the root pins exactly. scripts/check-module-versions.py enforces this in pre-commit and CI in every edition. The full pin table is on the release notes page.
| Pin | AWS Enterprise Baseline | Azure Enterprise Baseline | GCP Enterprise Baseline |
|---|---|---|---|
| OpenTofu, Terragrunt | 1.12.6, 1.1.6 | 1.12.6, 1.1.6 | 1.12.6, 1.1.6 |
| Cloud providers | hashicorp/aws ~> 6.65 | hashicorp/azurerm ~> 5.7, hashicorp/azuread ~> 3.10, Azure/azapi ~> 2.13 | hashicorp/google and hashicorp/google-beta ~> 8.5 |
| Other providers | helm ~> 3.3, kubernetes ~> 3.2 (web app) | time ~> 0.13 (four Baseline modules); helm ~> 3.3, kubernetes ~> 3.2, random ~> 3.7 (web app); databricks/databricks ~> 1.135 (ETL) | helm ~> 3.3 (Baseline runners); helm ~> 3.3, kubernetes ~> 3.2 (web app) |
| tflint ruleset | AWS ruleset 0.48.0 | tflint-ruleset-azurerm 0.32.0 | tflint-ruleset-google 0.40.0 |
| Modules | Registry modules, thin wrappers and custom modules | Custom thin modules only | Custom thin modules only |
Every edition runs tflint v0.64.0, and every edition disables the two rules that would flag each module for omitting required_version and required_providers, because those live in the generated versions.tf.
Where Terraform still shows
| Name | What it is |
|---|---|
terraform { source = ... } block | The Terragrunt block that names a unit's module, in every edition; the block name is inherited from the language. |
terraform.tfstate | The state file name under every AWS state key and in every Azure state blob name. |
terraform_version_constraint | The Terragrunt attribute that pins the engine, in every root.hcl. |
terraform-aws-modules/* (AWS) | The community registry modules the AWS edition pins, such as vpc 6.7.3 and eks 21.25.1. |
acme-terraform-deployer (AWS) | The deployer role in every account, beside acme-terraform-reader in every account and the acme-terraform-state-access and per-stage acme-terraform-state-<stage> roles in the management account. |
sa-acme-terraform-deployer (GCP) | The deployer service account of every project, Owner of its own project only. |
The Azure edition names its deployer identities after the repository and, for the blueprints, the stage, such as id-acme-azure-platform-baseline-deployer and id-acme-azure-blueprint-webapp-infra-dev-deployer, and uses no registry module. The engine itself is OpenTofu in every edition: the workflows install it with the OpenTofu setup action, the pre-commit hooks run tofu fmt, tofu validate and tofu docs, and every resource carries the tag ManagedBy = "opentofu" (the label managed_by = "opentofu" on GCP).
AWS Enterprise Baseline
The AWS edition sorts its modules into three tiers. A unit uses a registry module directly when inputs alone do the job (units/vpc-spoke uses terraform-aws-modules/vpc); a thin wrapper adds lookups or glue around a registry module (modules/eks, modules/s3, modules/lambda); a custom module exists where no suitable registry module does (modules/organizations, modules/ipam, modules/transit-gateway-routes). Registry modules are referenced as tfr:///terraform-aws-modules/<name>/aws?version=<pinned>.
The DocumentDB module generates its master password with an ephemeral resource and writes it through write-only arguments (master_password_wo, value_wo), so the password never appears in a plan or in state. Ephemeral resources and write-only arguments need OpenTofu 1.11 or later, which is one reason the repositories pin 1.12.
Azure Enterprise Baseline
The Azure edition's modules are custom and thin, one resource category per module, around native azurerm, azuread and azapi resources. root.hcl pins the three providers; the four modules key-vault, platform-key-vault, storage-account and container-apps-runners add the time provider, which waits for a role assignment to propagate before the next resource uses it. The web app infrastructure pins random ~> 3.7 in its root.hcl and declares helm and kubernetes in the modules that install charts; the ETL infrastructure declares the Databricks provider in its two Databricks modules. The OpenTofu explainer lists every provider and where it is used.
GCP Enterprise Baseline
The GCP edition's modules are custom and thin, one resource category each. root.hcl pins google and google-beta; the only Baseline module with an extra provider is github-runners, which installs the optional runners with helm. The web app infrastructure declares helm and kubernetes in the modules that install charts. The OpenTofu explainer lists every provider and where it is used.
Worked example: upgrading the Azure provider
On the Azure edition, an azurerm upgrade is one change to the ~> 5.7 constraint in root.hcl of each Azure infrastructure repository, plus the same pin in every module versions.tf the guard lists. The Baseline plan covers every unit in one run; the blueprint plans run once per stage in the dev, staging and prod matrix, and the reviewer looks for resource replacements. Rollback is reverting the pin. Because units are generated from one definition each, no unit file changes.
Common mistakes
- Pinning a provider inside a module that does not need to.
required_providersbelongs inroot.hcl; the guard fails a moduleversions.tfthat exists without a provider alias or an extra provider. - Running a different OpenTofu version locally. Use the versions in
root.hcland the workflows; a newer engine can write state an older pipeline cannot read. - Reading "Terraform" in a file name as a sign the engine is Terraform. The block names, the state file name and the registry namespace are shared; the binary is
tofu. - Upgrading a registry module and the provider in one change (AWS). Each upgrade is its own change with its own plan review; the Azure and GCP editions have no registry modules.