»Translating Protocol Version 6 to 5

The tf6to5server package enables translating a protocol version 6 provider server into a protocol version 5 provider server.

Use this package to:

• Migrate individual resources and data sources from terraform-plugin-sdk/v2 to terraform-plugin-framework over time, while maintaining Terraform CLI 0.12 and later compatibility.
• Develop with terraform-plugin-framework, but support Terraform CLI 0.12 and later.

Compatibility

Protocol version 5 provider servers are compatible with Terraform CLI 0.12 and later.

The following provider server implementations are supported:

• terraform-plugin-framework: A higher-level SDK that makes Terraform provider development easier by abstracting implementation details.
• terraform-plugin-go tf6server: A lower-level SDK to develop Terraform providers for more advanced use cases.

Requirements

Downgrading provider servers from protocol version 6 to protocol version 5 will return an error if there are protocol version 6 features that are in use that are not available in protocol version 5. Refer to the protocol version 6 documentation for more information.

If publishing to the Terraform Registry, set metadata.protocol_versions to ["5.0"] in the Terraform Registry manifest file.

Code Implementation

Use the tf6to5server.DowngradeServer() function to wrap a provider server. For most providers, this is in the provider main() function of the root directory main.go file or where tf5muxserver is implemented in the codebase, if applicable.

The following example downgrades a terraform-plugin-framework provider.

downgradedFrameworkProvider, err := tf6to5server.DowngradeServer(
    context.Background(),
    providerserver.NewProtocol6(frameworkprovider.New(version)())
)

downgradedFrameworkProvider, err := tf6to5server.DowngradeServer(
    context.Background(),
    providerserver.NewProtocol6(frameworkprovider.New(version)())
)

The following example uses tf5server to serve the downgraded provider directly.

err = tf5server.Serve(
    "registry.terraform.io/example/example",
    downgradedFrameworkProvider.ProviderServer,
)

err = tf5server.Serve(
    "registry.terraform.io/example/example",
    downgradedFrameworkProvider.ProviderServer,
)

The following example uses tf5muxserver to serve the downgraded provider while it is combined with other providers.

providers := []func() tfprotov5.ProviderServer{
    downgradedFrameworkProvider.ProviderServer,

    // Example terraform-plugin-sdk/v2 provider
    sdkprovider.New(version)().GRPCProvider,
}

muxServer, err := tf5muxserver.NewMuxServer(ctx, providers...)

providers := []func() tfprotov5.ProviderServer{
    downgradedFrameworkProvider.ProviderServer,

    // Example terraform-plugin-sdk/v2 provider
    sdkprovider.New(version)().GRPCProvider,
}

muxServer, err := tf5muxserver.NewMuxServer(ctx, providers...)

Refer to the tf5muxserver documentation for more details about how to serve the combined provider.

Testing Implementation

You can test the original provider using the same acceptance tests as before. Set the ProtoV5ProviderFactories field of TestCase to use the acceptance testing framework available in terraform-provider-sdk/v2/helper/resource.

The following example creates a test case for a downgraded provider.

resource.Test(t, resource.TestCase{
    // ... other TestCase fields ...
    ProtoV5ProviderFactories: map[string]func() (tfprotov5.ProviderServer, error) {
        "example": func() (tfprotov5.ProviderServer, error) {
            ctx := context.Background()
            downgradedFrameworkProvider, err := tf6to5server.DowngradeServer(
                ctx,
                providerserver.NewProtocol6(frameworkprovider.New("test")())
            )

            if err != nil {
                return nil, err
            }

            return downgradedFrameworkProvider.ProviderServer(), nil
        },
    },
})

resource.Test(t, resource.TestCase{
    // ... other TestCase fields ...
    ProtoV5ProviderFactories: map[string]func() (tfprotov5.ProviderServer, error) {
        "example": func() (tfprotov5.ProviderServer, error) {
            ctx := context.Background()
            downgradedFrameworkProvider, err := tf6to5server.DowngradeServer(
                ctx,
                providerserver.NewProtocol6(frameworkprovider.New("test")())
            )

            if err != nil {
                return nil, err
            }

            return downgradedFrameworkProvider.ProviderServer(), nil
        },
    },
})

Refer to the acceptance tests documentation for more details.