terraform-upgrade-assistant

Guides through Terraform version upgrades including identifying deprecated syntax, updating provider versions, and migrating breaking changes. This skill should be used when users need to upgrade Terraform or provider versions, fix deprecated warnings, or migrate configurations to newer syntax.

⭐7stars🔀1forks📁View on GitHub🕐Updated Nov 13, 2025

When & Why to Use This Skill

The Terraform Upgrade Assistant is a specialized Claude skill designed to streamline the complex process of upgrading Terraform versions and providers. It helps DevOps engineers and SREs safely navigate version migrations by identifying deprecated syntax, managing provider updates, and providing structured workflows for handling breaking changes. By automating the analysis of HCL code and offering step-by-step migration strategies, it minimizes the risk of infrastructure downtime and state file corruption during critical updates.

Use Cases

  • Terraform CLI Migration: Safely upgrading through major and minor CLI versions (e.g., 1.0 to 1.5) using a recommended incremental approach.
  • Provider Version Updates: Updating cloud provider versions (like AWS, Azure, or GCP) and resolving breaking changes in resource arguments and attributes.
  • Syntax Modernization: Identifying and fixing deprecated HCL syntax warnings to ensure code compatibility with the latest Terraform engines.
  • State File Troubleshooting: Resolving provider source mismatches and performing state replacement commands when migrating between provider registries.
  • CI/CD Pipeline Readiness: Preparing infrastructure code for automated pipeline upgrades by validating version constraints and pre-upgrade checklists.
nameterraform-upgrade-assistant
descriptionGuides through Terraform version upgrades including identifying deprecated syntax, updating provider versions, and migrating breaking changes. This skill should be used when users need to upgrade Terraform or provider versions, fix deprecated warnings, or migrate configurations to newer syntax.

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

1. Check Current Versions

# Check Terraform version
terraform version

# Check provider versions in use
terraform providers

# Check for available updates
terraform init -upgrade

2. Review Upgrade Guides

Before upgrading, review:

3. Upgrade Strategy

Incremental approach (recommended):

  1. Upgrade one minor version at a time
  2. Test thoroughly between upgrades
  3. Fix deprecation warnings before major upgrades

Example path: 1.0 → 1.1 → 1.2 → 1.3 → 1.4 → 1.5

4. 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