How to Safely Upgrade Your Terraform Provider

Upgrading a Terraform provider is one of the most common — and potentially dangerous — operations in infrastructure management. A single breaking change can trigger resource recreation, data loss, or unexpected downtime. This guide walks you through a battle-tested process for upgrading providers safely.

Why Provider Upgrades Matter

Terraform providers are plugins that translate your HCL configuration into API calls to cloud platforms like AWS, Azure, and GCP. When a provider updates, it can introduce:

• Breaking changes — Fields removed, renamed, or changed in type
• ForceNew changes — Modifications that destroy and recreate resources
• Deprecations — Features that will be removed in future versions
• Behavior changes — Subtle shifts in how resources are created or read
• New features — Optional capabilities that don't affect existing configs

Step 1: Pin Your Current Version

Before you upgrade, ensure your version constraint is explicit. A loose version constraint like >= 5.0 can cause unintended upgrades.

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "= 5.60.0"  # Pin to exact version
    }
  }
}

Run terraform providers lock to generate a lock file, ensuring consistent versions across all team members and CI pipelines.

Step 2: Review the Changelog

Before upgrading, read the release notes for every version between your current version and the target. Pay special attention to:

• BREAKING CHANGES sections
• NOTES about deprecations and migration paths
• Bug fixes that might change state behavior

Brief Stack Update Briefs provide structured diffs that highlight exactly which fields changed, with severity scoring to help you prioritize your review.

Step 3: Back Up Your State

Always back up your Terraform state before upgrading. If using a remote backend:

# For S3 backend
aws s3 cp s3://my-bucket/terraform.tfstate ./terraform.tfstate.backup

# For local state
cp terraform.tfstate terraform.tfstate.backup

If your backend supports versioning (like S3 with versioning enabled), ensure you can restore a previous state version.

Step 4: Upgrade in a Branch

Never upgrade a provider on your main branch. Create a dedicated branch:

git checkout -b upgrade/aws-provider-v6
# Update version constraint
terraform init -upgrade
terraform plan -out=upgrade.plan

Step 5: Run Plan and Analyze

The terraform plan output is your source of truth. Watch for:

• destroy/create — Resources being replaced (potential downtime)
• ~ update in-place — Fields changing (usually safe but verify)
• No changes — The ideal outcome for your existing resources

If the plan shows unexpected resource recreations, check if the upgrade introduced a ForceNew change on a field you're using.

Step 6: Test in a Non-Production Environment

Apply the upgrade in a staging or development environment first. Verify that:

1. All resources are created or updated as expected
2. No state drift appears after apply
3. A subsequent terraform plan shows no changes (clean state)
4. Application functionality is not affected

Step 7: Apply and Monitor

Once verified in staging, merge to your main branch and apply to production. After applying:

• Run terraform plan again — should show no changes
• Monitor your application health dashboards
• Verify any resources that were updated in-place are functioning correctly

Rollback Strategy

If the upgrade causes issues, rollback involves:

1. Revert the version constraint to the previous version
2. Restore state from backup if state was modified
3. Run terraform init to downgrade the provider
4. Run terraform plan to verify restore

Important: If the new provider version modified your state file format, downgrading may not be straightforward. This is why state backups are essential.

Best Practices Summary

• ✅ Always pin provider versions explicitly
• ✅ Read the changelog for every version you skip
• ✅ Back up state before every upgrade
• ✅ Use terraform plan before every apply
• ✅ Test in non-production first
• ✅ Keep upgrades small — don't skip many major versions
• ❌ Don't blindly upgrade in CI without plan review
• ❌ Don't upgrade multiple providers simultaneously