Add helper for upgrading a tfprotov5 server to a tfprotov6 server transparently.

[paddycarver]

terraform-plugin-go-contrib version

v0.1.0-dev

Use cases

We need a way to mux between terraform-plugin-sdk (v5) and terraform-plugin-framework (likely v6) and any providers built on terraform-plugin-go (v5 or v6). These projects are all going to use one of these two versions of the protocol, and we're going to want to be able to use mux with them, but that requires them to be on the same protocol version.

Attempted solutions

N/A

Proposal

Protocol version 5 is forward-compatible with protocol version 6--all its features exist and there's a direct 1:1 mapping for them. Because of this, it's possible for any protocol version 5 server to be transparently upgraded into a protocol version 6 server without any loss of fidelity or assumptions made on the part of the converter.

I'm proposing we add a tfprotov5tov6 package to this module which performs this upgrade between servers, converting a v5 server into a v6 server, allowing users to continue to use mux across the SDK, the framework, and plugin-go by calling a simple helper function.

References

N/A

[paddycarver]

So @bflad and I talked about this at some length, and decided we wanted to do two separate helpers:

1. A helper to upgrade from v5 to v6, which will always work, but only works with Terraform 1.0+
2. A helper to downgrade from v6 to v5, which will only work if nested attributes aren't used. Either an error should be returned or the provider should panic if nested attributes are found in the schema.

On further deliberation, we feel this probably shouldn't live in a contrib repository like this, where it's less likely to be discovered (given the relative frequency with which we expect it to be needed over the next year or two) and should probably live in terraform-plugin-mux, or maybe terraform-plugin-go directly.

The danger of including it in terraform-plugin-go directly is that if we ever want to change the API, it's going to be a breaking change for ~the entire ecosystem, which isn't great. But making it available there would make it easier to "upgrade" or "downgrade" providers built on terraform-plugin-go without having to go through muxing.

We can probably make that decision later. For now, I'm going to move the issue to plugin-mux, with the understanding that it could end up getting transferred to plugin-go later if it's decided that's a better place for it to live.

[bflad]

Once #37 and #39 are merged in some fashion, we'll have tf5testserver and tf6testserver implementations which should make testing these converters much easier without further duplicating test code.

[bflad]

A real blocking detail about muxing sdk/v2 and framework — protocol version 5 has a magic LegacyTypeSystem flag that sdk/v2 sets during ApplyResourceChange and PlanResourceChange to signal to CLI that the SDK doesn’t understand null values, ultimately turning off some consistency checks and only adding warning logs about the problem. Protocol version 6 does not include this flag. This means we are currently limited to muxing sdk/v2 and framework only in protocol version 5, otherwise really unexpected things could happen. Providers would need to fully convert everything over to framework before being able to shed sdk/v2 and upgrade to protocol version 6 with its new features.

If that’s an issue, we’ll need to immediately get a protocol update into Terraform CLI to carry forward that flag in version 6 of the protocol so sdk/v2 resources could still toggle that behavior when upgraded to protocol version 6 and muxed. It would be a weird situation though because we’d have to say framework+sdk/v2 mux support on protocol version 6 would only be available on Terraform CLI 1.1+ unless there’s a backport to 1.0.

[bflad]

Proposed addition of LegacyTypeSystem handling in protocol version 6:

Issue: hashicorp/terraform#30373
Pull Request: hashicorp/terraform#30375

[bflad]

terraform-plugin-go v0.7.0 contains the protocol addition and has been released. Will poke dependabot and update the dependency before continuing with this.

[github-actions]

I'm going to lock this issue because it has been closed for 30 days ⏳. This helps our maintainers find and focus on the active issues.
If you have found a problem that seems similar to this, please open a new issue and complete the issue template so we can capture all the details necessary to investigate further.