hashicorp / hashicorp/terraform-plugin-sdk

State migrations shouldn't require defining the Terraform Schema

Open
#875 0 comments 0 reactions 0 assignees View on GitHub
enhancement terraform-plugin-framework
Dominant language
Go
Stars
485
Forks
244
Avg merge
19h 57m
Merged PRs (30d)
4

Description

### SDK version

> github.com/hashicorp/terraform-plugin-sdk/v2 v2.10.1

### Use-cases

When performing state migrations, the new method `StateUpgraders` requires defining a point-in-time reference to the Terraform Schema - in contrast to the earlier approach for state migrations `MigrateState` which only required a migration function to be written.

This means that writing state migrations has become incredibly costly both in terms of time (initial development) and ongoing maintenance (since this is a large amount of boilerplate code required compared to the logic required for the migration itself).

### Attempted Solutions

The AzureRM Provider has wrapped the Plugin SDK to remove some of the boilerplate involves when writing a state migration, namely requiring only the fields within the Schema to be defined rather than returning a Terraform resource:

https://github.com/hashicorp/terraform-provider-azurerm/blob/ef2221b65a16b7a4f95f4374aa5540965a0a8029/internal/tf/pluginsdk/state_upgrades.go#L9-L58

.. whilst this approach does remove some boilerplate from each state migration, since the Plugin SDK requires specifying the Terraform Schema when creating a State Migration, we're still required to output these, which I'd estimate as 10-20x the size of the associated migration function.

It's worth noting that this wrapper function also validates that a state migration for the given version exists, which IIRC the implementation within the Plugin SDK doesn't do, but (IMO) would be worth adding at the same time.

Since this wrapper is a struct, this means that state migrations are defined in the Resource like so:

https://github.com/hashicorp/terraform-provider-azurerm/blob/ef2221b65a16b7a4f95f4374aa5540965a0a8029/internal/services/frontdoor/frontdoor_resource.go#L39-L43

### Proposal

Remove the requirement to specify the Terraform Schema when creating a State Upgrader - since in most cases this is mutating a single field (in our case generally the ID, which isn't defined in the Schema anyway).

Contributor guide

Open the contributing guide

Research direction

Start by reading the SDK's StateUpgraders and earlier MigrateState interfaces, then compare them with the AzureRM state-upgrade wrapper linked in the issue. Done means state migrations no longer require a full Terraform Schema, while preserving migration behavior and considering validation that the requested state-migration version exists.

Written by the indexing model from the issue text.

Assessment

Tech stack
go, terraform
Domain
devtools
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.