Introduction
This guide provides a detailed walkthrough for upgrading the AWS provider version in Terraform from v4.67.0 to v5.0.0. The article explains the recommended workflow, common errors, and their resolution and validation steps required to ensure a smooth and error-free upgrade in HCP Terraform.
Scenario
This article covers:
Step-by-step instructions for upgrading the AWS provider locally and within Terraform Cloud.
Two recommended approaches—a VCS-first workflow (preferred) and a local-first workflow.
Common upgrade-related errors and warnings, including why they occur and how to resolve them.
Validation steps to confirm that your Terraform configuration, state, and provider versions remain aligned after the upgrade.
Following this guide ensures your Terraform environment stays up-to-date, prevents state mismatch issues, and provides a reliable path to adopting new capabilities available in the AWS v5.x provider.
Steps to Upgrade AWS Provider Version :
Approach 1 [Preferred]
Resolve Errors in Main Branch
Fix all existing errors in the main branch.
-
Ensure that running
terraform planshows:No changes
No deletions
No modifications
Create a Feature Branch
Once the main branch is stable, create a feature branch from it.
Update AWS Provider
Update the AWS provider version directly in the VCS repository on the feature branch.
Create a Pull Request (PR)
Submit a PR with the updated provider version.
Verify that the PR results in a clean
terraform plan.
Update State File
If the PR plan is clean, run
terraform state refreshto update the state file.
Approach 2
1. Clone the VCS Repository
Start by cloning the repository that contains your Terraform configuration:
git clone <your-vcs-repo-url>
cd <repo-directory>2. Update Backend Configuration to Local
In your main.tf, temporarily switch to a local backend.
Comment out the Terraform Cloud backend block, or replace it with:
terraform {
backend "local" {}
}3. Remove Cached Terraform Files
Clean up existing cached files:
rm -rf .terraform
rm -f terraform.lock.hcl4. Update the AWS Provider Version
In your main.tf (or versions.tf), update the provider requirement:
terraform {
required_providers {
aws = {
source = "hashicorp/aws"
version = "~> 5.0.0"
}
}
}5. Initialize and Validate Locally
Run the following commands to initialize Terraform with the new provider:
terraform init
terraform plan
terraform applyThis step validates that your local environment is compatible with the AWS provider v5.0.0.
6. Revert Backend to Terraform Cloud
Once local validation is successful, update the backend configuration in main.tf back to Terraform Cloud:
terraform {
cloud {
organization = "your-org-name"
workspaces {
name = "your-workspace-name"
}
}
}7. Authenticate with Terraform Cloud
Login to Terraform Cloud:
terraform loginFollow the prompts and type yes when asked for confirmation.
Reinitialise Terraform with reconfiguration:
terraform init -reconfigureConfirm with yes when prompted.
8. Update the VCS Repository
Update the AWS provider version in your VCS repository (e.g., main.tf or versions.tf):
version = "~> 5.0.0"Commit and push the changes.
9. Validate in Terraform Cloud
Run:
terraform plan
terraform applyto confirm the upgrade was successful in Terraform Cloud.
Common Issue with this approach: Errors/Warnings After Terraform State Migration
After migrating Terraform state, you may encounter errors or warnings related to provider versions and unsupported attributes. Common messages include:
Errors:
-
Error: Resource instance managed by newer provider version-
Example:
The current state of aws_eks_cluster.simple was created by a newer provider version than is currently selected. Upgrade the aws provider to work with this state. The current state of aws_cloudwatch_event_rule.example was created by a newer provider version than is currently selected. Upgrade the aws provider to work with this state.
-
Warnings:
-
Warning: Failed to decode resource from state-
Example:
Error decoding "aws_cloudwatch_event_rule.example" from prior state: unsupported attribute "force_destroy" Error decoding "aws_eks_cluster.simple" from prior state: unsupported attribute "access_config"
-
Cause:
These errors occur when the migrated state was created using a newer version of the provider than the one currently configured.
Certain attributes introduced in newer provider versions are unsupported in the older version, causing decoding warnings.
Resolution:
Update the provider version in your VCS repository to match the version used to create the state.
Run
terraform init -upgradeto ensure the workspace uses the updated provider.Verify the state by running
terraform planto ensure no unintended changes are planned.
Notes:
Always review the
terraform planoutput after upgrading the provider to ensure compatibility with existing resources.This approach resolves both the “resource managed by newer provider” errors and the unsupported attribute warnings.
If you encounter any issue with the process, please reach out to HashiCorp Support Team https://support.hashicorp.com/hc/en-us for further assistance.