A tool upgrade replaces an infrastructure tool or plugin with a newer version while preserving, adapting, and testing the resources and configuration it manages. Large version gaps increase disruption risk, and complex IaC such as inline scripts may fail during migration. section 13.2
Prepare the upgrade by reducing hidden dependencies and uncontrolled changes:
- Decouple resource dependencies and use dependency injection where changed fields must be adapted between resource subsets. section 13.2.1
- Pin module, tool, and plugin versions so teams retain known configurations and avoid accidental breaking changes. section 13.2.1
- Deploy first to reduce drift, then choose an incremental upgrade path after reviewing breaking changes and compatibility. section 13.2.1
Staged upgrade with limited blast radius
Upgrade from version 1.7 to backward-compatible version 3.0 before moving to version 4.0. Freeze unrelated IaC changes, update high-level resources such as DNS and load balancers, run dry runs and tests, and then update lower-level resources with a rolling update. If an override script breaks on one server, repair or roll forward before affecting the remaining servers. section 13.2.2
Breaking-change migration
For a schema-changing upgrade from version 3.0 to 4.0, pin versions, release updated modules, copy the configuration into a new folder, and create separate tool state. Run the old blue resources and new green resources separately, then cut over traffic after validation. section 13.2.3
Figure 13.6 You plan your tool upgrade path and account for backward-compatible versions and versions with breaking changes.
Use the upgrade-path figure to compare incremental versions, backward-compatible steps, and breaking changes before implementation. section 13.2.1
