Summary: On this wiki page I will cover my experience in upgrading the AzureRM Terraform provider from version 3.112 to 4.51.
Date: 8 November 2025

Recently I had to upgrade the AzureRM terraform provider. We hadn't upgraded it in a while due to other priorities, but once these were addressed, I set about the task of upgrading the provider. On this page I will try to give some background on the process and the provider itself, as well as some of the issues I encountered.

The AzureRM provider is the official Terraform provider for managing Microsoft Azure resources. It is maintained by HashiCorp and Microsoft, and it allows users to define and manage Azure infrastructure using Terraform's declarative configuration language. The provider is regularly updated to add new features, fix bugs, and improve performance.

The latest version can be seen on the terraform registry. It allows you to check available resources and the available options for these resources.

Hashicorp, the company behind terraform, provides a general guide on upgrading providers. The process basically comes down to:

• Get your current deployment stable and working
  • Make sure you can do a `terraform init`, `terraform plan` and `terraform apply` without any issues
  • Create a backup of your terraform state file
  • Also install the latest version of the terraform CLI. Note that if you're running terraform from a pipeline on which you cannot control the terraform CLI version, you should install the same version as installed on the pipeline to avoid any discrepancies.
• Update provider configuration
  • Update the version in your `provider` block to the desired version
• Create a plan
  • Run `terraform init` to download the new provider version
    • Use the `-upgrade` flag to ensure that the latest version is downloaded
  • Run `terraform plan` to see what changes will be made
• Identify and document errors, warnings, or actions
  • Tackle one issue at a time. Start with errors, and only proceed to warnings once all errors are resolved. I had several occurences that after removing certain errors, also warnings dissapeared.
  • Refactor your configuration as needed
• Apply your plan
  • Run `terraform apply` to implement the changes

And an additional note, if you're working with a pipeline to deploy your terraform code, try to be able to perform `terraform plan` locally first. This will save you a lot of time.

This was our old provider block:

terraform {
  required_version = ">= 0.14.9"
 
  required_providers {
    azurerm = {
      source = "hashicorp/azurerm"
      version = "3.112"
    }
  }
}

And this is our new provider block. As you can see, only the version number has changed:

terraform {
  required_version = ">= 0.14.9"
 
  required_providers {
    azurerm = {
      source = "hashicorp/azurerm"
      version = "4.51.0"
    }
  }
}

The following commands were run in a PowerShell terminal on my local machine:

az login
az account set --subscription 30b3c71d-a123-a123-a123-abcd12345678
cd "C:\Repos\tf\applications\main"
terraform version
# Do a normal terraform init. It will tell you to use -upgrade to get the latest provider version
terraform init `
  -backend-config=storage_account_name="saeuwdevtf" `
  -backend-config=container_name="terraform" `
  -backend-config=key="dev.tfstate" `
  -backend-config=resource_group_name="rg-euw-dev-tf" `
  -backend-config=subscription_id="30b3c71d-a123-a123-a123-abcd12345678"
# So do a terraform init with -upgrade
terraform init `
  -backend-config=storage_account_name="saeuwdevtf" `
  -backend-config=container_name="terraform" `
  -backend-config=key="dev.tfstate" `
  -backend-config=resource_group_name="rg-euw-dev-tf" `
  -backend-config=subscription_id="30b3c71d-a123-a123-a123-abcd12345678" `
  -upgrade
# Then do a plan, and make sure to provide your tfvars file
terraform plan `
  -var-file="env/dev.tfvars" `
  -input="false"

When running the `terraform plan` command, several issues are to be expected. I'll address some of the issues I encountered below.

We had some resources with deprecated attributes. Especially the Kubernetes cluster resource had many attributes that were no longer supported. The way to tackle them is like this:

• Lookup the resource in the terraform registry
• Try to find the deprecated attribute. Sometimes it's only renamed, but then the description stayed the same. Other times it is completely removed. If that's the case it's isually mentioned in the old version of the documentation.
  • To find the old version of the documentation, you can use the version selector (it's almost at the top) on the terraform registry page of the resource.
• Rename or remove the attribute in your terraform code

Both on the kubernetes resource as well as on storage account we had some attributes that had new default values. This can happen because the new provider suddenly has support for an attribute and sets a default value different from the Azure default value. These settings are usually new, so you need to check them thoroughly. For example, on the storage account the options to allow for cross tenant copy got disabled. And for the kubernetes cluster the node upgrade channel got changed. This actually caused an node image upgrade during the night because I missed that during the plan.

We also had some errors and warning for the provider itself. It suddenly required a subscription id and also some of the attributes of the provider got renamed.

This was our old provider configuration:

provider "azurerm" {
  skip_provider_registration = true
  features {
    virtual_machine {
      skip_shutdown_and_force_delete = true
      delete_os_disk_on_deletion     = true
    }
  }
}

And this is our new provider configuration:

provider "azurerm" {
  subscription_id                 = var.env_subscription_id
  resource_provider_registrations = "none"
  features {
    virtual_machine {
      skip_shutdown_and_force_delete = true
      delete_os_disk_on_deletion     = true
    }
  }
}

Note that adding the subscription id solved a lot of decoding errors:

│ Warning: Failed to decode resource from state
│
│ Error decoding "module.restore_storage_account.module.diagnostic_settings.azurerm_monitor_diagnostic_setting.diagnostic_setting[0]"
│ from prior state: unsupported attribute "log"

Upgrading terraform providers can be a tedious task, especially when there are many breaking changes. However, by following a systematic approach and addressing issues one at a time, the process can be managed effectively. Always ensure to back up your state file before making any changes, and test thoroughly after the upgrade to ensure everything is functioning as expected. The whole process took me two working days with time for other issues and tasks as well in between.