Overview

This guide helps you migrate a Terraform provider from SDKv2 to the plugin Framework. We recommend migrating because the Framework has abstractions that make it easier to use, and it represents the future of Terraform plugin development. Refer to Plugin Framework Benefits for higher level details about how the framework makes provider development easier and Feature Comparison for a detailed functionality comparison between the SDKv2 and the framework.

This guide provides information and examples for most common use cases, but it does not discuss every nuance of migration. You can ask additional migration questions in the HashiCorp Discuss forum. To request additions or updates to this guide, submit issues or pull requests to the terraform-plugin-framework repository.

In addition to this migration guide, we recommend referring to the main Framework documentation as you migrate your provider.

Requirements

Before you migrate your provider to the Framework, ensure it meets the following requirements:

• Go 1.22+
• Built on the latest version of SDKv2
• The provider is for use with Terraform >= 0.12.0

Muxing

Consider muxing when you need to migrate a provider that contains many resources or data sources. Muxing enables multiple underlying provider implementations to exist within the same logical provider server. This lets you migrate individual resources or data sources to the Framework one at a time.

Refer to the muxing page of the migration guide for additional details.

Testing Migration

As you complete the migration, we recommend that you follow Test Driven Development by writing tests to ensure that the migration does not affect provider behavior. Refer to Testing Migration for details and an example.

Migration steps

Take the following steps when you migrate a provider from SDKv2 to the Framework:

• Ensure all tests pass.
• Consider finding SDKv2 resource data consistency errors, which might affect migrating to the Framework. Some errors can be resolved and verified with SDKv2 code before migration, if desired, otherwise resolving these errors must be part of the migration.
• Serve the provider via the Framework.
  • Implement muxing, if you plan to migrate the provider iteratively.
• Update the provider definition to use the Framework.
• Update the provider schema.
• Update each of the provider's resources and data sources.
  • Update related tests to use the Framework, and ensure that the tests fail.
  • Migrate the resource or data source.
  • Verify that related tests now pass.
• If you used muxing, remove the muxing configuration.