• HashiCorp Developer

  • HashiCorp Cloud Platform
  • Terraform
  • Packer
  • Consul
  • Vault
  • Boundary
  • Nomad
  • Waypoint
  • Vagrant
Terraform
  • Install
  • Tutorials
    • About the Docs
    • Configuration Language
    • Terraform CLI
    • Terraform Cloud
    • Terraform Enterprise
    • CDK for Terraform
    • Provider Use
    • Plugin Development
    • Registry Publishing
    • Integration Program
  • Registry(opens in new tab)
  • Try Cloud(opens in new tab)
  • Sign up
Plugin Development

Combining and Translating

Skip to main content
  • Combining and Translating
  • Combining Protocol v5 Providers
  • Combining Protocol v6 Providers
  • Translating Protocol v5 to v6
  • Translating Protocol v6 to v5

  • Resources

  • Tutorial Library
  • Certifications
  • Community Forum
    (opens in new tab)
  • Support
    (opens in new tab)
  • GitHub
    (opens in new tab)
  • Terraform Registry
    (opens in new tab)
  1. Developer
  2. Terraform
  3. Plugin Development
  4. Combining and Translating
  5. Translating Protocol v5 to v6
  • Plugin Mux
  • v0.7.x
  • v0.6.x

ยปTranslating Protocol Version 5 to 6

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

Use this package to:

  • Migrate individual resources and data sources from terraform-plugin-sdk/v2 to terraform-plugin-framework over time, while using protocol version 6 features in terraform-plugin-framework.
  • Develop with terraform-plugin-sdk/v2, but require Terraform CLI 1.0 or later.

Compatibility

Protocol version 6 provider servers are compatible with Terraform CLI 1.0 and later. Terraform CLI 1.1.5 and later is required to upgrade terraform-plugin-sdk/v2.

The following provider server implementations are supported:

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

Requirements

Upgrading provider servers from protocol version 5 to protocol version 6 has no provider code requirements.

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

Code Implementation

Use the tf5to6server.UpgradeServer() function to wrap a provider server. For most providers, this is either in the provider main() function of the root directory main.go file or where tf6muxserver is implemented in the codebase.

The following example upgrades a terraform-plugin-sdk/v2 provider.

upgradedSdkProvider, err := tf5to6server.UpgradeServer(
    context.Background(),
    sdkprovider.New(version)().GRPCProvider,
)

The following example uses tf6server to serve the upgraded provider directly.

err = tf6server.Serve(
    "registry.terraform.io/example/example",
    func() tfprotov6.ProviderServer {
        return upgradedSdkProvider
    },
)

The following example uses tf6muxserver to serve the upgraded provider while it is combined with others.

providers := []func() tfprotov6.ProviderServer{
    func() tfprotov6.ProviderServer {
        return upgradedSdkProvider
    },

    // Example terraform-plugin-framework provider
    providerserver.NewProtocol6(frameworkprovider.New(version)())
}

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

Refer to the tf6muxserver 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 ProtoV6ProviderFactories field of TestCase to use the acceptance testing framework available in terraform-provider-sdk/v2/helper/resource.

The following example creates a test for a combined provider.

resource.Test(t, resource.TestCase{
    // ... other TestCase fields ...
    ProtoV6ProviderFactories: map[string]func() (tfprotov6.ProviderServer, error) {
        "example": func() (tfprotov6.ProviderServer, error) {
            return tf5to6server.UpgradeServer(
                context.Background(),
                sdkprovider.New("test")().GRPCProvider,
            )
        },
    },
})

Refer to the acceptance tests documentation for more details.

Edit this page on GitHub

On this page

  1. Translating Protocol Version 5 to 6
  2. Compatibility
  3. Requirements
  4. Code Implementation
  5. Testing Implementation
Give Feedback(opens in new tab)
  • Certifications
  • System Status
  • Terms of Use
  • Security
  • Privacy
  • Trademark Policy
  • Trade Controls
  • Give Feedback(opens in new tab)