Migrate from SDKv2 to the plugin framework

This guide helps you migrate a Terraform provider from SDKv2 to the plugin framework. We recommend migrating your providers developed on SDKv2 to the plugin framework so that you can take advantage of the improved data abstractions and other features that make it easier to use. The framework also represents the future of Terraform plugin development. Refer to Plugin framework benefits to understand how the framework makes provider development easier and Feature comparison for a detailed comparison between the SDKv2 and the framework.

How to migrate a provider to the framework

To migrate your provider to the framework, rewrite the code for your provider, resources, data sources, and other Terraform features according to the libraries and data types provided by the framework. For providers that implement a small set of resources, data sources, and other Terraform features, you can implement the migration in a single release cycle. For more complex providers, we recommend using the terraform-plugin-mux module to help you release incremental versions of your provider. The module lets you multiplex (mux) features in SDKv2 and the framework in the same release.

The Terraform configuration for your provider's resources and other Terraform features should not change when migrating to the framework, and most migrations should not require users to modify their Terraform configuration. Remember to only introduce breaking changes to your provider in major version updates.

Migrate in a single release cycle

Complete the following steps to migrate your provider in a single release cycle:

1. Ensure that your SDKv2 provider uses up-to-date versions of the Go language and SDKv2 and includes comprehensive unit tests.
2. Migrate each resource, data source, and other Terraform feature from SDKv2 to the framework.
3. Remove the SDKv2 from your provider codebase.
4. Ensure that your tests continue to pass to avoid introducing breaking changes to your provider.
5. Release the framework version of your provider.

For detailed instructions, refer to the recommended workflow.

Migrate over multiple release cycles

Complete the following steps to implement SDKv2 and framework versions of your provider with the terraform-plugin-mux module so that you can migrate your provider over multiple release cycles:

1. Ensure that your SDKv2 provider uses up-to-date versions of the Go language and SDKv2 and includes comprehensive unit tests.
2. Implement the terraform-plugin-mux module in your provider server.
3. Incrementally migrate each resource, data source, and other Terraform feature from SDKv2 to the framework. Ensure that your tests continue to pass to avoid introducing breaking changes to your provider.
4. Follow your normal release process during the migration to release bug fixes and other updates alongside migration changes.
5. Once you have migrated your provider, schema, and all resources and other Terraform features to the framework, remove SDKv2 from your provider.

For a more detailed set of steps, follow our recommended workflow to migrate your provider from SDKv2 to the framework.

Test your migration

We recommend following the test-driven development (TDD) methodology. In TDD, developers write tests then write code that passes. TDD helps ensure that the migration does not affect provider behavior. Refer to Test migrated code for details and examples.

Framework tutorials

Before migrating your provider to the framework, you may wish to familiarize yourself with the framework by completing the plugin framework tutorial collection.

Framework documentation

While migrating your provider, refer to the framework documentation in addition to this migration guide.