Upgrade terraform versions from 0.12.x and higher

upgrade-terraform-versions.md

Upgrade Terraform

• If using an arm instance, versions before 1.0.2 may cause intermittent issues so some commands will have to be repeated if they fail.
• Before each upgrade, the required_version may need to be updated
• After each upgrade, a terraform refresh may be needed

Prereqs

• Start with terraform that does not have any changes
• tfenv - brew install tfenv
• asdf - brew install asdf
• aws2-wrap - optional - brew install aws2-wrap.
  • If the aws provider is really old (pre v3), the AWS_PROFILE may not work and so the terraform commands would need to be prefixed with aws2-wrap to use the env var.

For good measure, before beginning, re-authenticate if using sso via aws sso login

To 0.12

tfenv

tfenv install latest:^0.12
tfenv use latest:^0.12

asdf

asdf install terraform 0.12.31
asdf local terraform 0.12.31

The rest

terraform --version
rm -rf .terraform/
rm -f .terraform-version
# switch to a workspace if one is applicable
# terraform workspace select xyz
terraform init -upgrade
# replace-providers. you may need to replace additional ones.
terraform 0.12upgrade -yes

There are many manual changes too

• https://developer.hashicorp.com/terraform/language/v1.1.x/upgrade-guides/0-12
• https://kraigm.medium.com/upgrade-terraform-0-11-to-0-12-8d636439c0fa

terraform init
terraform apply

To 0.13

tfenv

tfenv install latest:^0.13
tfenv use latest:^0.13

asdf

asdf install terraform 0.13.7
asdf local terraform 0.13.7

The rest

terraform --version
rm -rf .terraform/
rm -f .terraform-version
# switch to a workspace if one is applicable
# terraform workspace select xyz
terraform init -upgrade
# replace-providers. you may need to replace additional ones.
terraform state replace-provider -auto-approve "registry.terraform.io/-/aws" "hashicorp/aws"
terraform 0.13upgrade -yes
terraform init
terraform apply

To 0.14

tfenv

tfenv install latest:^0.14
tfenv use latest:^0.14

asdf

asdf install terraform 0.14.11
asdf local terraform 0.14.11

The rest

terraform --version
rm -rf .terraform/
rm -f .terraform-version
# switch to a workspace if one is applicable
# terraform workspace select xyz
terraform init
terraform apply

To 0.15.x+

After 0.14.x the tfstate is said to be pretty stable and different patch versions can apply the same terraform module/directory without needed the exact version.

The same steps for 0.14 can be repeated for 0.15.5, 1.0.x, 1.1.x, 1.2.x, etc

asdf local terraform 0.15.5
asdf local terraform 1.0.11
asdf local terraform 1.1.9
asdf local terraform 1.2.9
asdf local terraform 1.3.9

troubleshooting

Initialing backend errors

Error: error configuring S3 Backend: Error creating AWS session: SharedConfigErr: only one credential type may be specified per profile: source profile, credential source, credential process, web identity token, or sso

Error: error configuring S3 Backend: no valid credential sources for S3 Backend found.

Please see https://www.terraform.io/docs/language/settings/backends/s3.html for more information about providing credentials.

Error: : Session token not found or invalid

This usually happens with AWS SSO. Try unsetting any ^AWS env variables and use the aws2-wrap command.

env | grep -i ^aws

aws2-wrap --profile <profile> --exec "terraform init && terraform apply"

If errors persist, try re-authenticating via aws sso login.

Incompatible provider version

│ Error: Incompatible provider version │ │ Provider registry.terraform.io/hashicorp/template v2.2.0 does not have a package available for your current platform, │ darwin_arm64.

terraform state replace-provider -auto-approve "registry.terraform.io/hashicorp/template" "cloudposse/template"

# versions.tf
terraform {
  required_providers {
    template = {
      source  = "cloudposse/template"
      version = "~> 2"
    }
  }
}

NOTE: This will not work for a root module that consumes a module that uses the hashicorp/template provider. In this case, the consumed module must also have the above required_providers block defined which is a limitation in terraform.