Migration workflow

For providers that only implement a few resources and other Terraform features, you can follow the workflow to migrate your provider in a single release cycle. For complex providers that support a number of resources and other Terraform features, we recommend that you follow the workflow to migrate over multiple release cycles to incrementally migrate your provider to the framework. Migration to the framework should not require any changes to configuration that uses your provider. Remember to only introduce breaking changes to your provider in major version updates.

Migrating to the framework

This migration 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 learn more about the Terraform provider framework, refer to the framework documentation. To learn about the benefits of migration from SDKv2, refer to the migration guide.

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

To reduce the risk of introducing breaking changes during migration, we strongly recommend that your ensure adequate test coverage before you begin migrating your provider to the framework.

Migrate in a single release cycle

To migrate your provider in a single release cycle, follow the steps below.

Ensure the SDKv2 version of your provider has sufficient test coverage and that all tests pass.
Review your provider code for SDKv2 resource data consistency errors, which might affect migrating to the framework. Some errors can be resolved and verified with SDKv2 code before you begin migration. Otherwise, you will need to resolve these errors as part of the migration.
Serve your provider via the framework.
Update the provider definition to use the framework.
Update the provider schema to use the framework.
Update each of the provider's resources, data sources, and other Terraform features to use the framework.
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.
Remove any remaining references to SDKv2 libraries.
Verify that all of your tests continue to pass.
Once you have completed the migration process and verified that your provider works as expected, release a new version of your provider.

Migrate over multiple release cycles

To migrate your provider incrementally across multiple release cycles, you will use the terraform-plugin-mux module to implement a multiplex (mux) provider server.

Follow the steps below.

Ensure the SDKv2 version of your provider has sufficient test coverage and that all tests pass.
Review your provider code for SDKv2 resource data consistency errors, which might affect migrating to the framework. Some errors can be resolved and verified with SDKv2 code before you begin migration. Otherwise, you will need to resolve these errors as part of the migration.
Serve your provider via the framework.
Implement a mux server for your provider.
Update the provider definition to use the framework.
Update the provider schema to use the framework.
Update each of the provider's resources, data sources, and other Terraform features to use the framework.
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.
During migration, follow your normal release process to fix bugs and add features to your provider. By relying on a mux server and test-driven development, the migration should not affect users of existing configuration.
Remove the mux server configuration from your provider, as well as any remaining references to SDKv2 libraries.
Verify that all of your tests continue to pass.
Once you have completed the migration process and verified that your provider works as expected, release a new version of your provider.