Terraform AzureRM 4.0 : ce qui casse et comment migrer

HashiCorp a publié le provider AzureRM 4.0 en août 2024. Si vous gérez de l’infrastructure Azure avec Terraform, vous êtes concerné, et pas dans le genre “on bumpe la version et on passe à autre chose”. Les montées de version majeure suivent semver, ce qui signifie que les breaking changes sont explicitement autorisés. Des ressources sont renommées, des attributs disparaissent, des valeurs par défaut changent, et votre terraform plan qui fonctionnait parfaitement commence à afficher des diffs inattendus.

Nous avons migré plusieurs codebases de production de AzureRM 3.x vers 4.0 au cours des dernières semaines. Cet article couvre ce qui casse réellement, les nouvelles fonctionnalités, et comment aborder la migration sans exploser vos fichiers state.

Guide de mise à jour : AzureRM 4.0 Upgrade Guide - AzureRM Provider Changelog

Pourquoi les montées de version majeure comptent

Les providers Terraform ne sont pas comme des dépendances applicatives où vous pouvez bumper une version mineure et lancer vos tests. Les versions majeures de providers modifient le contrat entre votre code HCL et l’API Azure. Une ressource qui existait en 3.x peut être renommée, scindée en deux, ou supprimée entièrement en 4.0.

Si vous avez un pin avec ~> 3.0, vous n’obtiendrez pas la 4.0 automatiquement : c’est voulu. Mais chaque équipe qui reste sur 3.x accumule de la dette de migration. Plus vous attendez, plus la migration sera conséquente.

Les breaking changes principaux

La version 4.0 touche énormément de ressources. Voici les changements qui impactent la plupart des codebases :

Les valeurs par défaut des attributs ont changé

C’est le piège vicieux. Des attributs qui avaient une valeur par défaut en 3.x ont maintenant une valeur différente. Votre code ne change pas, mais le comportement si :

# 3.x - public_network_access_enabled was implicitly true
resource "azurerm_storage_account" "example" {
  name                     = "stexample"
  resource_group_name      = azurerm_resource_group.rg.name
  location                 = "westeurope"
  account_tier             = "Standard"
  account_replication_type = "LRS"
}

# 4.0 - you need to be explicit about changed defaults
resource "azurerm_storage_account" "example" {
  # ... same base config ...
  public_network_access_enabled = true  # was implicit, now required
}

Changements de configuration du provider

Le bloc features a subi plusieurs modifications ou suppressions de sous-blocs. Certains flags qui se trouvaient dans features{} ont été déplacés vers des attributs au niveau de la ressource :

# 3.x provider block
provider "azurerm" {
  features {
    key_vault {
      purge_soft_delete_on_destroy = true
    }
  }
}

# 4.0 - some feature flags moved to resource attributes
provider "azurerm" {
  features {}
  # key_vault purge behavior is now on the resource itself
}

Documentation Registry : AzureRM Provider Configuration - 4.0 Breaking Changes List

Provider-Defined Functions : la grande nouveauté

La version 4.0 ne se résume pas aux breaking changes. Elle introduit les provider-defined functions, une fonctionnalité de Terraform 1.8 qui permet aux providers de fournir leurs propres fonctions :

locals {
  parsed = provider::azurerm::parse_resource_id(
    "Microsoft.Network/virtualNetworks",
    azurerm_virtual_network.example.id
  )
}

output "vnet_name" {
  value = local.parsed.resource_name
}

Cela remplace le pattern fragile split("/", resource_id) que tout le monde utilisait. La fonction du provider comprend la structure des resource ID Azure et gère les cas limites que le découpage de chaînes de caractères ne gère pas.

Important : les provider-defined functions nécessitent Terraform 1.8 ou plus récent. Mettez à jour vos contraintes de version :

terraform {
  required_version = ">= 1.8"
  required_providers {
    azurerm = {
      source  = "hashicorp/azurerm"
      version = "~> 4.0"
    }
  }
}

Documentation Terraform : Provider-defined Functions - Terraform 1.8 Release

L’approche de migration

N’essayez pas de tout migrer d’un coup. Cette approche a fonctionné pour nous sur plusieurs codebases de production :

1. Fixez la version 3.x et auditez. Avant de toucher à la version du provider, identifiez chaque type de ressource que vous utilisez et vérifiez-le par rapport au guide de mise à jour. Sachez ce qui change avant de changer quoi que ce soit.

2. Migrez de manière incrémentale. Traitez les ressources impactées un module ou un stack à la fois. Commencez par les renommages d’attributs simples et progressez vers les cas plus complexes.

3. Utilisez les blocs moved pour les renommages. Quand un type de ressource a changé mais que la ressource Azure sous-jacente reste la même, les blocs moved gèrent cela de manière déclarative :

moved {
  from = azurerm_some_old_resource.example
  to   = azurerm_some_new_resource.example
}

C’est plus sûr que terraform state mv parce que c’est review dans le code et appliqué pendant le terraform apply. Utilisez terraform state mv uniquement quand vous devez déplacer des ressources entre des fichiers state ou scinder une ressource en deux.

4. Lancez un plan dans une branche. Bumpez le provider, lancez terraform init -upgrade, puis terraform plan sur chaque environnement. N’appliquez pas, lisez juste l’output :

terraform init -upgrade
terraform plan -out=migration.tfplan 2>&1 | tee plan-output.txt
# Resources marked for destruction = investigate before proceeding
# In-place updates = verify the attribute changes
# No changes = this module is clean

Toute ressource affichant “destroy and recreate” nécessite une investigation avant d’appliquer quoi que ce soit.

Les pièges courants

azurerm_resource_group_template_deployment : l’attribut output_content est passé d’une chaîne JSON à une map. Si vous le parsez avec jsondecode(), supprimez cet appel, c’est déjà décodé.

Network security rules : les attributs liés aux NSG ont changé de valeurs par défaut et de règles de validation. Les security rules inline dans azurerm_network_security_group nécessitent une comparaison minutieuse du plan.

Les valeurs booléennes par défaut ont changé : plusieurs booléens sont passés de true à false ou inversement. C’est la catégorie de changements la plus dangereuse, car votre code ne change pas mais le comportement change silencieusement. Lisez chaque ligne du diff du plan.

subscription_id obligatoire : le provider 4.0 est plus strict sur la configuration du subscription. Si vous comptiez sur la détection implicite, vous devrez le définir explicitement dans le bloc provider.

Stratégie de test

Ne vous fiez pas uniquement à un terraform plan vert. Pour chaque module : lancez d’abord un plan sur 3.x pour capturer une baseline, bumpez vers 4.0 et relancez un plan, puis comparez l’output ligne par ligne. Appliquez d’abord en dev, ne migrez jamais la production sans avoir validé dans un environnement inférieur. Vérifiez le portail Azure après application, car certains changements d’attributs sont cosmétiques dans le plan mais significatifs dans Azure.

Ne sautez pas l’étape, ne la bâclez pas

Les mises à jour majeures de providers sont pénibles. La version 4.0 touche des centaines de ressources, et chaque codebase rencontrera au moins quelques breaking changes.

Mais ignorer la mise à jour n’est pas une option. L’équipe AzureRM ne backportera pas le support de nouvelles ressources vers 3.x. Chaque nouveau service Azure, chaque nouvelle fonctionnalité d’API, arrive uniquement en 4.x. Plus vous restez sur 3.x, plus vous prenez du retard, et vous finirez par devoir migrer de 3.x vers 5.x, ce qui sera deux fois plus douloureux.

Fixez la version à ~> 4.0, migrez votre codebase et restez à jour. Configurez Dependabot ou Renovate pour signaler les mises à jour de versions mineures. Traitez les mises à jour de providers comme n’importe quelle maintenance de dépendances : ennuyeux, nécessaire, et bien plus facile quand c’est fait régulièrement. Votre futur vous vous remerciera quand la 5.0 sortira et que la migration sera un travail d’une journée au lieu d’un projet d’une semaine.

Ressources : AzureRM 4.0 Upgrade Guide - Terraform Version Constraints - AzureRM Provider GitHub

Plus sur le blog

15 février 2024 | 9 min de lecture

Bicep vs Terraform, pourquoi Terraform est notre choix par défaut (et quand Bicep l'emporte)

Azure Terraform Bicep

12 novembre 2025 | 8 min de lecture

Pourquoi chaque entreprise Azure a besoin d'une méthodologie d'analyse WAF

Azure WAF Security

1 juin 2022 | 11 min de lecture

Container Apps vs AKS vs App Service : un cadre de decision

Azure Containers AKS