How to Upgrade AWS Provider Version in HCP Terraform

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 plan shows:

  1. No changes

  2. No deletions

  3. 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 refresh to 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.hcl

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

This 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 login

Follow the prompts and type yes when asked for confirmation.

Reinitialise Terraform with reconfiguration:

terraform init -reconfigure

Confirm 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 apply

to 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:

1. Update the provider version in your VCS repository to match the version used to create the state.

2. Run terraform init -upgrade to ensure the workspace uses the updated provider.

3. Verify the state by running terraform plan to ensure no unintended changes are planned.

Notes:

• Always review the terraform plan output 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.