Upgrade Terraform: v0.11 to v0.12

Terraform v0.12 includes config-level improvements, so you’ll need to consider some changes when upgrading. This guide covers the most common upgrade concerns and issues.

Some simple configurations will require no changes at all, and most other configurations can be prepared by running the automatic upgrade tool. 

What we will spend most of our time in upgrading the in-use different providers and it’s dependent configurations. As usually we see state drift issues as soon as we upgrade the provider version and we want to fix them.

Pre-requisites for upgrade:

• First upgrade your version to last 0.11.x version which should be 0.11.15, as this will also help enable  “terraform 0.12checklist” command.
• Run a clean terraform init & terraform apply to make sure the config and actual state are in sync. 
• Run terraform 0.12checklist command to see if there are any pre-upgrade steps in the checklist. 
• Install tools like tfswitch or tfenv to easily switch between terraform versions.

Addendum: Invalid Module Names

Terraform v0.12 enforces stricter naming rules, rejecting modules with names starting with digits, which were allowed in v0.11 due to a validation bug. To fix this before upgrading:

1. Rename the module in your configuration.
2. Run terraform state mv module.old module.new in v0.11.14 to update the state.
3. Apply the configuration to sync the state with the latest changes before upgrading to avoid issues.

This will ensure your module names are compliant and prevent state snapshot errors during the upgrade.

Upgrading to Terraform 0.12

Before switching to Terraform 0.12, we recommend using Terraform v0.11.15

Now, once you have a clean terraform apply and the state is in sync with no changes pending. Switch over to Terraform v0.12.x release you can use tools like tfswitch & tfenv for installing different version easily. 

Terraform 0.12upgrade Command

Now once we have upgraded the terraform version to v0.12.x and we can run the “terraform 0.12upgrade” command to make our config v0.12 ready, we also need to make sure if we are using any dependent modules we need to run this command in that directory as well.

Although, terraform won’t do all the changes you would need to safely move to v0.12.x but it will do some syntax changes here and there to save us some time.

Correct Provider Version

We need to choose the most recent compatible provider versions for our existing providers in use, you can only use provider version which is supported by v0.12.x.

Code-Level Examples & Common Adjustments

Google Provider Compatibility Adjustments

• Interpolation Syntax Changes: Terraform v0.12 simplifies how variable interpolation works. In v0.11, interpolation required wrapping variables and expressions in ${}, but in v0.12, simpler syntax allows direct references without wrapping.
• Lists and Maps: v0.12 provides built-in support for handling complex data structures like lists and maps without workarounds.

Using Conditional Expressions for Count

• Count Parameter: In v0.12, conditional logic for count is simpler, allowing direct if-else style conditions like var.create_instance ? 1 : 0

# Terraform 0.11 - Conditional Creation Workaround
resource "google_compute_instance" "optional_instance" {
  count = "${var.create_instance ? 1 : 0}"  # Conditional expression required wrapping
  name  = "optional-instance"
}

# Terraform 0.12 - Simplified Conditional Creation
resource "google_compute_instance" "optional_instance" {
  count = var.create_instance ? 1 : 0  # Direct if-else condition without wrapping
  name  = "optional-instance"
}

Type Constraints

• Terraform v0.12 enforces stricter type constraints. Variables should have explicitly defined types (e.g., string, list, map) to prevent conflicts.

# Defining a List Variable in v0.12
variable "tags" {
  type    = list(string)  # Define variable as a list of strings
  default = ["web", "dev"]
}

Additional Best Practices

• Testing in Development: Always test configurations in a separate development environment after upgrading, before moving to production.
• State File Backup: Backup the state file before upgrading. Store backups in a secure location to avoid data loss.
• Review Release Notes: Refer to Terraform’s release notes for any updates affecting specific resources or configurations.

Following these steps and best practices will help ensure a stable upgrade from Terraform 0.11 to 0.12.