Skip to main content
Mapagam

Upgrading Terraform

1. Checking Version Compatibility

Version Compatibility Status Notes
Terraform 1.8 NEW Latest stable release as of 2026
Terraform 1.7 DEPRECATED Support ended in 2025
Terraform 1.6 Supported Active support and bug fixes
Terraform 1.5 Supported Active support and bug fixes
Terraform 1.4 Supported Active support and bug fixes
Terraform 1.3 Supported Active support and bug fixes
Terraform 1.2 Supported Active support and bug fixes
Terraform 1.1 Supported Active support and bug fixes
Terraform 1.0 Supported Active support and bug fixes
Terraform 0.15 DEPRECATED Support ended in 2024
Terraform 0.14 DEPRECATED Support ended in 2024
Terraform 0.13 DEPRECATED Support ended in 2023
Terraform 0.12 DEPRECATED Support ended in 2023
Terraform 0.11 DEPRECATED Support ended in 2022
Terraform 0.10 DEPRECATED Support ended in 2021
Terraform 0.9 DEPRECATED Support ended in 2020
Note: Always check the official upgrade notes for any breaking changes or migration steps before upgrading.

Example: Checking Terraform Version

terraform version

2. Upgrading Terraform Binary

Version Release Date Notes
v1.8.0 2025-04-15 Latest stable release with new features and improvements
v1.7.5 2025-03-20 Security patch release
v1.6.7 2025-02-10 Stable release with bug fixes

Example: Upgrade Terraform Binary on macOS (Homebrew)

brew update
brew upgrade terraform

Example: Upgrade Terraform Binary on Linux (via package manager)

sudo apt update
sudo apt install terraform

Example: Manual Download and Install (Linux x86_64)

cd /tmp
wget https://releases.hashicorp.com/terraform/1.8.0/terraform_1.8.0_linux_amd64.zip
unzip terraform_1.8.0_linux_amd64.zip
sudo mv terraform /usr/local/bin/
Note: Ensure that the new binary version is compatible with your existing configurations and state files.
Warning: Back up your Terraform state files before upgrading to prevent data loss.

3. Upgrading Provider Versions

Version Release Date Notes
aws v5.0.0 2023-10-10 Major release with breaking changes; requires updates to resource configurations
aws v4.50.0 2023-08-15 NEW Support for new regions and services
aws v4.0.0 2023-01-20 DEPRECATED Removed support for legacy features

Example: Updating Provider Version in Configuration

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
    }
  }
}

Example: Migrating from Old to New Provider

resource "aws_instance" "example" {
  ami           = data.aws_ami.ubuntu.id
  instance_type = "t3.micro"
  # Updated attribute names or values as needed
}
Note: Always run terraform init after updating provider versions to ensure compatibility.
Warning: Provider upgrades may introduce breaking changes. Review the release notes before upgrading.

4. Using Terraform Upgrade Commands

Command Description Flags Notes
terraform init Initializes a Terraform working directory -upgrade Upgrades the Terraform version if needed
terraform plan Generates and displays an execution plan -upgrade Ensures compatibility with newer versions
terraform apply Applies the changes required to reach a desired state -upgrade Upgrades modules and providers during apply

Example: Upgrading Terraform version

terraform init -upgrade

Example: Upgrading provider versions

terraform plan -upgrade
Note: The -upgrade flag ensures that Terraform uses the latest compatible versions of providers and modules.

5. Updating State Format

When upgrading Terraform versions, the state file format may change. Terraform handles most state format updates automatically during terraform init or terraform apply. However, in some cases, manual intervention is required.

Version State Format Change Action Required Notes
0.12.x State format changed to support new syntax and features Yes, if using older state files State files from 0.11 and earlier must be upgraded using terraform state replace-provider
1.0+ State format includes new metadata and improved performance No Automatic upgrade during terraform init

Example: Upgrading State Format

terraform init
# Terraform will automatically upgrade the state file if needed
Note: Always backup your state file before performing upgrades to avoid data loss.
Warning: Downgrading Terraform versions after an upgrade may cause compatibility issues or data corruption. Always ensure the state file is compatible with the target version.

6. Handling Breaking Changes

Note: Breaking changes in Terraform typically occur between major versions (e.g., 1.x to 2.x). Always review the official upgrade guide for each version.
Change Type Description Action Required Impact
Resource Schema Changes Fields or attributes of resources may be removed, renamed, or restructured. Update configuration files to align with new schema. Configuration must be updated to prevent errors during apply.
Provider API Changes Providers may drop support for older APIs or change behavior. Update provider versions and adjust configurations accordingly. Resource state may become invalid or require migration.
Function and Expression Syntax Some expressions or built-in functions may be deprecated or replaced. Replace deprecated syntax with updated equivalents. Plans or applies may fail if outdated expressions are used.

Example: Updating Resource Schema

# Before (Terraform 1.0)
resource "aws_instance" "web" {
  ami           = "ami-12345678"
  instance_type = "t2.micro"
  ebs_optimized = true
}

# After (Terraform 1.5)
resource "aws_instance" "web" {
  ami           = "ami-12345678"
  instance_type = "t2.micro"
  ebs_optimized = false
}

Steps to Handle Breaking Changes

  • Review release notes for the target version.
  • Use terraform plan to identify configuration issues.
  • Update provider versions in required_providers.
  • Run terraform init to fetch updated providers.
  • Apply changes with terraform apply.
Warning: Always backup your state file before performing major upgrades.

7. Testing Upgrades

Example: Test Upgrade Workflow

terraform init
terraform plan -upgrade
terraform apply
Step Description Action
1. Initialize Prepare Terraform for upgrade terraform init
2. Plan Upgrade Review changes before applying terraform plan -upgrade
3. Apply Changes Execute the upgrade terraform apply
Note: Always test upgrades in a non-production environment first.
Warning: Ensure all state files are backed up before upgrading.

8. Using Version Constraints

Constraint Description Examples Notes
~> 1.0 Allows patch and minor updates, but not major version changes ~> 1.0.0 Equivalent to >= 1.0.0, < 2.0.0
~> 1.2 Allows patch updates, but not minor or major version changes ~> 1.2.0 Equivalent to >= 1.2.0, < 1.3.0
= 1.2.3 Exactly matches the specified version = 1.2.3 Strict version match
>= 1.0.0 Allows any version greater than or equal to the specified version >= 1.0.0 Useful for pinning minimum versions
< 2.0.0 Allows any version less than the specified version < 2.0.0 Useful for avoiding breaking changes in major versions

Example: Using version constraints in a Terraform module

terraform {
  required_version = ">= 1.0.0, < 2.0.0"
}

module "aws_instance" {
  source  = "terraform-aws-modules/ec2-instance/aws"
  version = "~> 3.0"
}
Note: Version constraints in Terraform are defined using the required_version attribute in the terraform block and the version attribute for modules.
Warning: Using = for version constraints can lead to issues if you don't update the constraint when new versions are released. It's generally better to use ~> for more flexibility.

9. Managing Provider Version Locks

Provider version locks ensure consistent behavior across environments and prevent unexpected upgrades. Terraform uses the .terraform.lock.hcl file to track provider versions.

Lock File Field Description Example
provider Provider identifier (e.g., registry.terraform.io/hashicorp/aws) provider "registry.terraform.io/hashicorp/aws"
version Exact version of the provider version = "5.0.0"
constraints Version constraints (e.g., >= 4.0, < 6.0) constraints = ">= 4.0, < 6.0"
hashes SHA256 hashes of provider binaries hashes = ["sha256:..."]

Example: Lock File Entry

provider "registry.terraform.io/hashicorp/aws" {
  version = "5.0.0"
  constraints = ">= 4.0, < 6.0"
  hashes = [
    "sha256:...",
  ]
}
Note: The .terraform.lock.hcl file is auto-generated and should not be manually edited. Use terraform init to update or regenerate it.
Warning: If you manually edit the lock file, Terraform may not recognize the changes and could lead to inconsistent behavior or errors during plan/apply.

Managing Provider Locks

  • Lock file ensures reproducible environments.
  • Use terraform init to update or regenerate lock files.
  • Locks are generated from required_providers in configuration.
  • Locks prevent automatic provider upgrades unless explicitly requested.

10. Rolling Back Upgrades

Step Description Action
1 Identify the previous version Check terraform version or review release notes to determine the previous stable version.
2 Backup state files Copy terraform.tfstate and any remote state backups to a safe location.
3 Revert binary Download and install the previous version of Terraform from the official releases page.
4 Validate configuration Run terraform init and terraform validate to ensure compatibility.
5 Reapply state If necessary, restore the backed-up state file to resume operations.
Note: Rolling back may not always be possible if state migrations occurred or if resources were modified in a way that's incompatible with older versions.

Example: Reverting Terraform Binary

curl -O https://releases.hashicorp.com/terraform/1.5.7/terraform_1.5.7_linux_amd64.zip
unzip terraform_1.5.7_linux_amd64.zip
sudo mv terraform /usr/local/bin/terraform

Was this article helpful?

Related Cheat Sheets