Meta Issue: Support for terraform-plugin-framework

[jackofallops]

NOTE: This Meta Issue is tracking upgrading the Provider to using hashicorp/terraform-plugin-framework, which will enable a number of improvements to the Provider. Updates will be provided in this Meta Issue as things progress, rather than on the individual linked issues, to centralise the updates.

Overview

Currently the Provider makes use of hashicorp/terraform-plugin-sdk@v2 (and Terraform Protocol v5) to build Data Sources and Resources. Whilst this works well and we've been able to build out a considerable number of both Data Sources and Resources - we're hitting up against limitations of the design and Terraform Protocol itself and currently have a number of issues which require changes at that level to fix.

The next version of the Terraform Protocol (v6) is available in hashicorp/terraform-plugin-framework and enables the use of new functionality that should allow us to fix a number of these issues. Map-nested attributes in particular is a feature that should alleviate several of the issues listed at the bottom.

resource "azurerm_linux_virtual_machine" "example" {
  disks = {
	“one” = {
...
}
	“two” = {
...
}
  }
}

Adoption of Terraform Protocol v6 will be accompanied by a change in the underlying schema types for certain resources in order to support the use of map nested attributes. This will require breaking configuration changes and as such, wants to be done in unison across the Provider to avoid noticeable variations in the user experience across the provider. An example of the breaking configuration changes required will be use of an assignment operator for nested lists, sets and maps e.g.

Current:

resource "azurerm_linux_virtual_machine" "example" {
  network_profile {
...
  }
  image_reference {
...
  }
}

Post Framework:

resource "azurerm_linux_virtual_machine" "example" {
  network_profile = {
...
  }
  image_reference = {
...
  }
}

Whilst it's possible to adopt hashicorp/terraform-plugin-framework using v5 of the Terraform Protocol, doing so will not solve a number of issues that we’re expecting hashicorp/terraform-plugin-framework to solve since the bug-fixes we're looking for rely on v6 of the Protocol, such as the use of map nested attributes mentioned above.

Rather than using the hashicorp/terraform-plugin-sdk@v2 types directly, we're moving in the direction of using the Typed SDK to build (Typed) Data Sources and Resources instead - which (at runtime) generates a wrapper for these Data Sources/Resources that allows them to be exposed using hashicorp/terraform-plugin-sdk@v2.

In order to support exposing resources via hashicorp/terraform-plugin-framework, our intention is to implement a compile-time feature toggle to allow compiling down to hashicorp/terraform-plugin-framework or hashicorp/terraform-plugin-sdk@v2.

Notably only Data Sources and Resources that make use of the Typed SDK will be exposed when using the hashicorp/terraform-plugin-framework compilation mode - meaning that Untyped Data Sources and Resources (using hashicorp/terraform-plugin-sdk@v2 directly) need to be migrated to being Typed Data Sources/Resources.

In addition, it's worth calling out that we're intentionally opting to use the Typed SDK across the Provider since this allows us to provide better behavioural consistency.

Status of this work

Due to the breaking configuration changes explained above that will occur when new functionality is introduced after adoption of hashicorp/terraform-plugin-framework this work will need to ship as a part of a major release, however given the size and extent of the work required this will not be included in the next 4.0 major release of the provider.

Related Issues

Support for disk attachment to VMs at creation time
Support for specifying an existing disk to attach an azurerm_disk_access resource to
Support for Importing OSDisk of azurerm_linux_virtual_machine / azurerm_windows_virtual_machine
azurerm_windows_virtual_machine fails to create when referencing a "specialised" shared gallery image
Support for managed_disk_id from an existing OS Disk
Ordering of the request_routing_rule blocks in azurerm_application_gateway
(more to be added)

[hkrutzer]

Due to the breaking configuration changes explained above that will occur when new functionality is introduced after adoption of hashicorp/terraform-plugin-framework this work will need to ship as a part of a major release, however given the size and extent of the work required this will not be included in the next 4.0 major release of the provider.

v4 was just released, it looks like v3 was released in 2022 and v2 in 2020. Should we expect terraform-plugin-framework with v5, with a similar timeline, meaning somewhere in 2026?