Terraform Upgrade Assistant
This skill helps safely upgrade Terraform and provider versions.
When to Use
Use this skill when:
-
Upgrading Terraform CLI version
-
Updating provider versions
-
Fixing deprecated syntax warnings
-
Migrating to new provider features
-
Preparing for major version upgrades
Upgrade Process
- Check Current Versions
Check Terraform version
terraform version
Check provider versions in use
terraform providers
Check for available updates
terraform init -upgrade
- Review Upgrade Guides
Before upgrading, review:
-
Terraform Upgrade Guides
-
Provider changelog (e.g., AWS provider releases)
-
Breaking changes documentation
- Upgrade Strategy
Incremental approach (recommended):
-
Upgrade one minor version at a time
-
Test thoroughly between upgrades
-
Fix deprecation warnings before major upgrades
Example path: 1.0 → 1.1 → 1.2 → 1.3 → 1.4 → 1.5
- Update Version Constraints
Before
terraform { required_version = ">= 1.0"
required_providers { aws = { source = "hashicorp/aws" version = "~> 4.0" } } }
After
terraform { required_version = ">= 1.5"
required_providers { aws = { source = "hashicorp/aws" version = "~> 5.0" } } }
Handling Deprecation Warnings
Identify Warnings
Run plan to see warnings
terraform plan
Example output:
Warning: Argument is deprecated
Use aws_s3_bucket_acl resource instead
Upgrade Checklist
Pre-Upgrade
-
Backup state file
-
Review upgrade guides for target version
-
Check provider changelogs
-
Test in non-production environment first
-
Ensure team is aware of upgrade
During Upgrade
-
Update version constraints in code
-
Run terraform init -upgrade
-
Run terraform plan and review changes
-
Fix any deprecation warnings
-
Update CI/CD pipelines with new version
Post-Upgrade
-
Run terraform plan (should show no changes)
-
Test apply in dev environment
-
Update documentation
-
Commit version constraint changes
-
Monitor for issues
Troubleshooting
State File Compatibility
If state file is incompatible with provider source
terraform state replace-provider
registry.terraform.io/-/aws
registry.terraform.io/hashicorp/aws
Provider Plugin Issues
Clear provider cache and reinitialize
rm -rf .terraform/ rm .terraform.lock.hcl terraform init -upgrade
Version Constraint Best Practices
Good - Allows patch updates, prevents breaking changes
terraform { required_version = "~> 1.5.0" # 1.5.x only
required_providers { aws = { source = "hashicorp/aws" version = "~> 5.0" # 5.x only } } }
Too restrictive
required_version = "= 1.5.0" # Only exact version
Too permissive
required_version = ">= 1.0" # Could break on major updates