Skip to content
On this page 7

OpenTofu and Terragrunt for enterprise IaC

OpenTofu and Terragrunt give enterprise IaC a license you control and a dependency graph that plans an entire new environment before any of it exists.

OpenTofu is the community fork of Terraform; Terragrunt is the orchestration layer around it. Together they give an infrastructure codebase two properties a long-lived cloud foundation needs: a license that cannot be changed underneath you, and a dependency graph explicit enough that an entire new environment can be planned before a single resource exists.

Those are the two reasons, and neither is fashion. The rest of this post is the evidence, the migration path, and the cases where a different tool is the better engineering decision.

Why the license question comes up at all

#

Terraform was MPL 2.0 from 2014 until August 2023, when HashiCorp relicensed it under the Business Source License 1.1. BUSL is source-available: you can read the code and use it, and you cannot use it to offer a competing product. IBM completed its acquisition of HashiCorp in February 2025.

For almost every enterprise, none of that is a legal problem. You run the tool internally, the additional use grant covers you, and your counsel will say so in a paragraph. The problem is a different one, and it is a governance problem rather than a legal one: the terms under which your build works can be changed by an organization that is not you, at a moment you do not choose. A cloud foundation is a ten-year artifact. The thing that renders it should not need re-evaluating every time a vendor changes owner.

OpenTofu is the fork made in answer to that. It is MPL 2.0, it is hosted by the Linux Foundation, it has a public RFC process, and its contributors come from several companies rather than one. The license answer is therefore short: the code you already have is permanently MPL, and nobody can relicense the project without forking it, at which point you keep what you have. Since the fork the two tools have also diverged on features — OpenTofu added client-side state encryption, early variable evaluation and provider for_each — so “drop-in replacement” describes your existing code rather than the two projects’ futures.

What does Terragrunt actually add?

#

Terragrunt is not a language. It is a thin wrapper that does four things, and every one of them is a response to repetition.

  1. One root configuration, generated everywhere. Backend settings, provider blocks, the role to assume, default tags and version constraints are written once and generated into each unit at run time. Change the tagging policy in one file and every unit in the repository picks it up.
  2. A unit is a state boundary. One directory, one configuration, one state key. This is the single most consequential structural decision in the repository, and it deserves its own post — Terraform state at enterprise scale is that post.
  3. Declared dependencies with typed outputs. A unit says which other units it needs and reads their outputs by name. Nobody copies a VPC ID into a variable file.
  4. Orchestration across the graph. One command plans or applies many units in dependency order, which is what makes a fifteen-account apply a pipeline step rather than a runbook with a checklist.

Stacks are the newer piece and the one that scales. A stack file declares a set of units from a template plus the values that differ, so “a workload account” exists once as a definition rather than four times as a copy. In the AWS Enterprise Baseline, 22 stack files and 52 unit definitions generate 88 units across 15 accounts from 38 modules. Adding a fifth workload account is a map entry and a folder: two pull requests, no new architecture.

That ratio is the argument. If your environment has no ratio like it — if you have one environment and one account — Terragrunt is overhead, and the honest recommendation is further down this page.

How can a new environment plan before it exists?

#

Here is the problem every multi-unit codebase hits. Unit B needs the VPC ID that unit A produces. Unit A has not been applied. So B cannot plan, and you find out whether B was written correctly only after A is real. Teams accept this and apply in waves, discovering a typo in wave four with three waves of resources already created.

A dependency block can carry mock outputs: placeholder values for the outputs of a unit that does not exist yet, used only when the real outputs are unavailable, and configured to apply to plan and validate but never to apply. With complete mocks, the whole environment plans from nothing.

Figure 1
Planning a dependent unit before its dependency exists

On the plan path, the network unit has not been applied, so the workload unit reads mock outputs and still produces a full plan for review. On the apply path, the network unit is applied first and the workload unit reads its real outputs. Mock values are never used during an apply.

plan, nothing exists yetnetwork unitnot appliedmock outputsworkload unitplans in fullreviewon the PRapply, in dependency ordernetwork unitapplied firstreal outputsworkload unitapplied secondmocks never used
With mock outputs, a unit can be planned against a dependency that has not been applied. The reviewer reads the plan for the entire environment before any resource exists; the apply then uses only real outputs.

The catch is that mocks rot. Someone adds an output to a module, does not add it to the mock, and plan-before-apply quietly stops working for that unit — which nobody notices until the next environment build, because everything else still plans fine against real state.

So the mock completeness becomes a test. In the AWS Enterprise Baseline, one of eight guard scripts running on every pull request checks that dependency mock outputs are complete — every attribute the unit actually reads, not merely a block that exists, because a partial mock is no better than none. The other five reject hardcoded CIDR blocks (addresses come from the IPAM address map, not from a variable someone typed), verify the address map itself, verify the stack layout the generator expects, verify that module versions are pinned, and verify that required inputs are present. Every one of them was written after its convention broke once, which is the only honest way these lists ever get made. Guard scripts are cheap and they catch the class of mistake that code review is worst at: the thing that is absent. There is more on that pattern in the golden path for new services.

Two details make mocks safe rather than merely convenient. They are restricted to validate and plan, so a mock value can never reach the cloud. And they are written as obvious sentinels — account identifiers made of zeros, resource identifiers containing the word mock, addresses from a reserved range — so that if one ever did surface in a real plan, nobody would mistake it for a fact.

How do you migrate from Terraform?

#

Three steps. Each is independently valuable and none of them forces the next.

StepWhat you doWhat to watchHow you know it worked
1. Swap the binaryInitialize with OpenTofu against the same state and backendVersion-pin the binary in CI and locally; check any provider or language feature added after the forktofu plan returns no changes on an unchanged codebase
2. Wrap the modulesKeep root modules as they are; add one Terragrunt configuration per environment that generates backend and provider blocks and declares dependenciesState keys do not have to move, and moving them is a separate change with its own riskThe same empty plan, now produced through Terragrunt
3. Adopt stacksReplace copied environment folders with a stack file plus valuesOnly worth doing where you have several of somethingAdding an environment is a map entry, not a copy

Step one is usually an afternoon. The thing to be rigid about: if the plan after the swap is not empty, stop. A non-empty plan means something interpreted your configuration differently, and the safe move is to understand it rather than to let an apply reconcile it. That is the same discipline described in drift is a fact, not a failure — a difference is information, and the response to information is not to apply.

Step two is where most of the work is, and it is the step that pays. Step three is optional, and a team that stops at step two has a perfectly respectable codebase.

One principle covers the harder migrations — from CloudFormation, from a console-built account, from an existing organization built with another tool. At no point may two tools manage the same resource. Adoption is done with import blocks, which sit in the code next to the resource they claim, so taking ownership of an existing organization is a reviewed diff with a plan attached rather than a command someone ran. Where a thing already exists and cannot be duplicated — an organization, for instance — importing it is the only correct move, and a tool that offers to create a second one is telling you the code is wrong.

When is plain Terraform or CDK the better choice?

#

Recommending this toolchain for everything would be dishonest. It is a fit for repetition, multiple accounts and a long horizon. Outside that, other choices win.

Your situationThe better choiceWhy
One team, one account, a few dozen resourcesPlain OpenTofu or Terraform, no wrapperTerragrunt’s value is entirely in removing repetition. With no repetition it is a layer to learn and debug for nothing
The people writing infrastructure are application developers who will not write HCLAWS CDK or PulumiTypes, loops, abstraction and unit tests in a language the team already knows. The constraint to accept with CDK is CloudFormation underneath it: resource coverage, stack limits, and whole-stack rollback on a failed update
Your organization already runs HCP Terraform with policy-as-code and a team that operates itTerraform on HCPYou have already paid the integration cost. Switching buys a license property you may not need enough to justify the churn
A single application, deployed to one cloud, with a platform the vendor managesThe platform’s own toolingIf you never wanted to own the infrastructure layer, adopting a foundation toolchain is the wrong shape of answer
Ten or more accounts, several regions, repeated environments, a ten-year horizonOpenTofu with TerragruntThis is the ratio the toolchain exists for, and the license property matters most on the longest timescale

The same honesty applies to the alternatives to building any of it. AWS Control Tower with Account Factory for Terraform, the Landing Zone Accelerator, Cloud Posse’s reference architectures and Gruntwork’s IaC library all solve overlapping problems, and for a team that wants to assemble and operate the pieces themselves, they are real options with real communities.

What it looks like in a delivered foundation

#

The AWS Enterprise Baseline is written in OpenTofu and Terragrunt, using Terragrunt Stacks, and pinned: OpenTofu 1.12.6, Terragrunt 1.1.6, AWS provider ~> 6.65, with every GitHub Action pinned by commit SHA. It is 38 modules, 52 unit definitions and 22 stack files generating 88 units across 15 accounts in 2 organizational units, with 3 workflows and 8 guard scripts.

Two conventions in that code matter more than any module. Every value specific to a deployment is tagged TODO: and every optional choice is tagged @optional:, with the price of the paid ones written in the comment beside the switch. You can read the repository and find every decision that was made for you, which is the opposite of a foundation whose defaults are discovered during an incident.

The pipeline is the ordinary one and it is the point: a pull request produces a plan posted as a comment, review happens on the plan, merge triggers an apply across the accounts in dependency order, and production is gated by an environment with required reviewers. Nothing is applied from a laptop. If that sounds like a lot of ceremony, it is roughly the same ceremony as a code review, and it is the difference described in if deployment requires a hero, it isn’t automated.

The code is delivered into your repositories and your accounts, source-available under the PolyForm Internal Use License 1.0.0, built on open-source tooling. What the BuiltForProd Baseline adds on top of the tools is the decisions: which units exist, what depends on what, and which switches are on.

Where to start this week

#
  1. Run the binary swap in a scratch branch. Initialize with OpenTofu against a copy of a non-production state and confirm an empty plan. You now know the size of the decision instead of debating it.
  2. Count your copies. How many directories differ only by an environment name? That number is what Terragrunt would remove, and if it is one, do not adopt it.
  3. Try to plan an environment that does not exist. If you cannot, you have found the reason deployments feel like discovery.
  4. Write one guard script. The cheapest is “no hardcoded CIDR blocks”. It takes an hour and it will find something.

If you would rather have the structure already decided and the guards already written, the BuiltForProd Blueprints sit on top of exactly this toolchain, and the BuiltForProd Assessment measures what you have today against the BuiltForProd Standard before anyone proposes changing it.

Questions

Is OpenTofu a safe choice for an enterprise foundation?

OpenTofu is licensed under MPL 2.0 and governed by the Linux Foundation with a public RFC process and contributors from several companies. State and configuration are compatible with Terraform 1.5.x, and the major cloud providers are the same providers. The practical risk is not the fork; it is whether your team pins versions and reads release notes, which is true of any tool in a delivery pipeline.

What does Terragrunt do that OpenTofu cannot?

It removes repetition and makes dependencies explicit. Backend configuration, provider blocks, assume-role settings and default tags are written once and generated into every unit. Each unit gets its own state key. Dependencies between units are declared rather than copied by hand, which is what makes orchestrating an apply across many accounts possible.

What is dependency mocking, and why does it matter?

A dependency block can supply placeholder values for the outputs of a unit that has not been applied yet. Those placeholders are used only during a plan, so a reviewer can read the full plan for an environment that does not exist. Without it, you discover mistakes in wave four of an apply instead of in review.

How hard is it to migrate from Terraform to OpenTofu?

The binary swap is usually an afternoon: initialize with OpenTofu against the same state and confirm the plan is empty. If the plan is not empty, stop and find out why before applying anything. Adding Terragrunt on top is a separate, larger piece of work and does not have to happen at the same time.

When is plain Terraform or CDK the better choice?

Plain Terraform or OpenTofu with no wrapper is better when there is one environment, one account and little repetition, because Terragrunt buys you nothing there. CDK or Pulumi is better when the people writing infrastructure are application developers who will not write HCL and who want types, loops and unit tests in a language they already use.

This is what we build.

BuiltForProd deploys a production foundation into your own cloud accounts, hands over the repositories and the documentation, and, if you want it, keeps running it with your team. Tell us what you are running and what is coming next. The first call is 30 minutes, with an engineer who scopes engagements, not a salesperson.

The calendar invite and the video link go to this address. Prefer to write? Send a message instead.

Terraform state at enterprise scale

Terraform state is a production system: one key per unit, a real lock, versioning, and a restore drill. Here is what to do when state and reality diverge.

The golden path for new services

A golden path turns a platform team from a ticket queue into a paved road: what it must include, the new-repository flow, and the 18 pitfalls to design out.