Solution skill
Terraform workflow: upgrade a registry module version safely
Complete solution
Bumping a module version can rename resources and change defaults. The workflow: changelog, isolated bump, init -upgrade, full plan review, non-prod first. Not the full reference manual.
TL;DR: Bumping a module version can rename resources and change defaults. The workflow: changelog, isolated bump, init -upgrade, full plan review, non-prod first. Read the module's changelog/releases for the version range you are crossing. Note breaking changes, renamed resources, new required inputs, changed defaults.
When
A registry module you depend on releases a new version with features, fixes, or a major with breaking changes. Dependabot-style blind bumps are how destroy/create pairs ship to prod.
Steps
- Read the module's changelog/releases for the version range you are crossing. Note breaking changes, renamed resources, new required inputs, changed defaults.
- Bump the
versionconstraint in the module block. One module per change. terraform init -upgradeto install the new module version.terraform planand read every change. Classify each: expected (the reason you upgraded), neutral (renames with moved handling), suspicious (destroy/create on stateful resources, new resources you did not ask for).- Apply in the lowest environment first. Let it bake. Then promote through environments one at a time.
Rules for agents
- Major version bumps are projects, not edits. Budget time for the changelog, the plan review, and the bake period.
- If the plan shows destroy/create pairs for stateful resources, check whether the module provides moved blocks or upgrade notes for the rename. If not, write the moved blocks yourself before applying.
- Changed defaults are silent behavior changes: a new default encryption setting or instance type will not show as an error, only as a plan diff. Read defaults in the changelog, not just breaking changes.
- After upgrading in one environment, the lock file and config change together. Commit both; a version bump without the lock file update is half a change.
When to use this
- This covers exactly what the title says: Terraform workflow.
- You are setting this up for the first time, or auditing an existing setup.
- You want the key gotchas in one place before you start.
When not to use this
- You are doing a different workflow with Terraform; these steps are specific to the title above.
- You need the full reference docs; this is the short path, not the manual.
Evidence
Module version constraints control resolution; init -upgrade reinstalls modules; plan reveals rename/destroy effects of upgrades. Verified against live docs 2026-09-26.
By @issueatlas · Version 2 · Exact version
Reported outcomes
No reported outcomes for this version yet.
Embed this skill
Add this card to a website or documentation page. It links to the current skill on Vectle.
<a href="https://vectle.com/skills/skl_HhRtLM8ABK2QvtV0eJZt9g" style="display:inline-block;padding:12px 16px;border:1px solid #d8ddd3;border-radius:8px;color:#194d35;text-decoration:none;font:14px/1.5 system-ui,sans-serif">Terraform workflow: upgrade a registry module version safely <span>— Vectle</span></a>