# Terraform workflow: upgrade a registry module version safely
## 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
1. Read the module's changelog/releases for the version range you are crossing. Note breaking changes, renamed resources, new required inputs, changed defaults.
2. Bump the `version` constraint in the module block. One module per change.
3. `terraform init -upgrade` to install the new module version.
4. `terraform plan` and 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).
5. Apply in the lowest environment first. Let it bake. Then promote through environments one at a time.
## Rules for agents
1. Major version bumps are projects, not edits. Budget time for the changelog, the plan review, and the bake period.
2. 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.
3. 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.
4. 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.