Terraform State and Backend Operations · Topic 3 of 3
Dependency Chains and Terraform Upgrades
Terraform Professional 002: find what blocks an upgrade with terraform providers and graph, then move Terraform versions through environments safely.
- 6 min
- Every module's
required_versionandrequired_providersmust be satisfied, not just the root's. terraform init -upgradeworks within constraints, so an exact pin must be edited first.terraform graphoutputs DOT text;terraform providerstraces requirements per module.
What it is
An upgrade rarely touches one thing. The Terraform CLI version is constrained by your root module and every child module, modules constrain providers, and other stacks read the state you write.
A dependency chain is that series of links. Finding it first tells you what must change and in what order.
How it works
The links to check
| Link | Where to look | Tool |
|---|---|---|
| CLI version | required_version in root and every module | terraform version |
| Provider versions | required_providers in every module | terraform providers |
| Selected providers | .terraform.lock.hcl | terraform init |
| Module versions | version on registry module blocks | Reading the configuration |
| Resource order | References and depends_on | terraform graph |
| State readers | terraform_remote_state in other stacks | Search other repositories |
terraform providers shows provider requirements and where each was detected, per module. It also lists providers required by state, so it can show a dependency on a provider that the configuration no longer mentions.
Reading the resource graph
terraform graph | dot -Tpng > graph.png
terraform graph -type=plan -draw-cycles
Without -type, the output is a simplified graph of ordering among resource and data blocks. It is DOT text, not an image, so Graphviz renders it. The -type values are plan, plan-refresh-only, plan-destroy and apply.
References create implicit edges, and depends_on creates explicit ones for what Terraform cannot infer. A replaced resource splits into destroy and create nodes, which is why a provider upgrade that forces replacement can affect everything downstream.
Walkthrough: tracing a blocked upgrade
A team on Terraform 1.14 wants 1.15, and the root configuration looks like this.
terraform {
required_version = "~> 1.14.0"
}
module "net" {
source = "acme/network/aws"
version = "2.3.0"
}
~> 1.14.0allows 1.14.x only, so Terraform 1.15 fails withUnsupported Terraform Core version.- Assume module 2.3.0 also declares a
required_versionthat excludes 1.15. Raising the root constraint alone still fails, because every module's constraint must hold. - A newer module release supports 1.15, so change
versionin themoduleblock.terraform init -upgradealone cannot help, because an exact pin allows only 2.3.0. - Assume the new module requires a newer provider than the lock file records.
terraform initthen fails with "does not match configured version constraint", andterraform init -upgraderesolves it. - Run
terraform plan, and review the lock file diff before committing.
The chain was CLI, then module, then provider.
Version constraints for the CLI
| Constraint | Behavior |
|---|---|
"1.15.0" | Every upgrade needs an edit |
">= 1.15.0" | Also accepts future major versions, so it is too loose for production |
"~> 1.15.0" | Allows patch updates only; the style HashiCorp suggests for pinning major and minor |
required_version applies only to the CLI, not to providers. If it is not met, Terraform errors and takes no action.
The upgrade order
Upgrades within v1.x are designed to work without special steps, and you can jump from any v1.x release to a later one. Downgrades are not guaranteed.
State is the one-way door. Each snapshot records the version that wrote it, and a CLI that does not support the snapshot's state file format errors with text such as state snapshot was created by Terraform v1.7.5, which is newer than current v0.12.29. Downgrading within v1.x is not guaranteed, and no supported path takes a project back to an older state format.
That has three consequences for ordering:
- Upgrade readers in order. Stacks that read this state through
terraform_remote_statemust be able to read what the new version writes, so plan the order across stacks and move readers no later than writers. - Upgrade every user together. Laptops and CI runners must move as well, because an older version is not guaranteed to work with state a newer one wrote.
- Separate changes. Do not combine a Terraform upgrade with a provider upgrade or a refactor, or you cannot tell which one caused a plan diff.
Start from a clean plan, so a later diff can be attributed to the upgrade. Afterward, a no-change plan is the evidence that it was safe. Keep a state backup or use a versioned backend, because restoring a snapshot is the realistic way back.
How the exam asks about this
- "A registry module pinned to an exact version does not support the target Terraform." Change the version argument, then run terraform init -upgrade.
- "After one engineer upgraded, a teammate's older CLI errors on state." The state uses a format their CLI does not support; they must upgrade.
- "Find where each provider requirement comes from." Run terraform providers.
What to remember for the exam
- Every module's
required_versionandrequired_providersmust be satisfied, not just the root's. terraform init -upgradeworks within constraints, so an exact pin must be edited first.terraform graphoutputs DOT text;terraform providerstraces requirements per module.moved,importandremovedblocks each need a minimum Terraform version, so adopting a feature raises it for that configuration.- An older CLI errors on a state format it does not support, and downgrades are not guaranteed, so move readers and users in a planned order.
- Go through dev, then staging, then production, with a plan review at each step.
Do not delete .terraform.lock.hcl or edit state to get past a version error. Change the constraint that is blocking you, and let terraform init -upgrade update the selection.
Common mistakes
Changing only required_version. That only states what the CLI may be. It does not update modules or providers, and it does not install anything.
Upgrading production first because it is urgent. The first write in the new version cannot be undone with a supported path. Prove the upgrade in lower environments, where a bad result is cheap.
Forgetting consumers of remote state. Your apply can succeed and still leave another team's older CLI unable to read the snapshot you wrote. Find readers before you begin.
Check yourself
Why might raising
required_versionin the root not be enough?Child modules declare their own constraints, and all of them must be satisfied, so a module may also need a new version.
Does
terraform graphproduce an image?No. It prints DOT text, which you pipe to Graphviz
dotor another renderer.What happens when an older CLI reads a state file format it does not support?
It errors and asks you to upgrade, because there is no supported way back to an older state format.
Topic 3 of 3 in Terraform State and Backend Operations
Test yourself on Terraform State and Backend Operations
The full HashiCorp Terraform Infrastructure Engineer Professional question bank has 600 questions, with timed practice exams and an explanation for every answer.
This study guide is independent and is not affiliated with, endorsed by, or sponsored by HashiCorp. Vendor names, certification names and exam codes are trademarks of their respective owners and are used for identification only.