The creation of the terraform-plugin-mux Go module was a pragmatic, separate extension to the terraform-plugin-go ecosystem to enable provider developers to support multiple SDKs within a single logical provider. Later, functionality was added to enable the translation of protocol version 5 to version 6, so provider developers could opt into nested attribute support for new resource implementations but at the cost of only supporting more modern versions of Terraform (e.g. 1.x) since providers announce protocol support at the provider server level. The functionality in this Go module operates a low-to-the-protocol level, similar to that of terraform-plugin-go's provider server implementations.
While the separation of concerns and versioning between terraform-plugin-mux and terraform-plugin-go has the benefits of reducing friction for mux releases, there are a few considerations that were not clear or present when it was introduced:
It was unclear whether this abstraction was necessary at all. The ecosystem usage seems to suggest that yes, it is, at least until the ecosystem more fully migrates off terraform-plugin-sdk. For some larger providers (e.g. hashicorp/aws), they may need this functionality for months or years. It does, however, represent an advanced use case and is generally temporary until the provider can afford a major version update. Some provider developers will instead skip the mux step by opting for wholesale migrating SDKs and do the major version update all at once because the temporary implementation and extra effort may not be worth it.
It was unclear whether this abstraction would eventually have stable versioning, which would be a difference from terraform-plugin-go. While stable versioning could potentially be introduced, the amount of documentation and ecosystem burden does not seem worth it for the minor benefit it would provide.
Introducing the abstraction felt like it needed clear naming to separate it from other SDK functionality and that clear naming was worth promoting at the Go module naming level.
Introducing the abstraction felt like it needed its own documentation separate from other SDK functionality.
The plugin protocol was extremely stable, where provider functionality was rarely changing or being enhanced. This is no longer true and in fact, may accelerate further. This means that protocol level features must be implemented essentially twice in terraform-plugin-go and terraform-plugin-mux to fully enable the ecosystem.
The last point is the latest main driver for this considering this effort. Effectively and "safely" introducing protocol changes right now requires a dance of terraform-plugin-go and terraform-plugin-mux changes to prevent provider developers from needing to upgrade all their SDK dependencies at once, e.g.
Introduce temporary interface types for new RPCs into terraform-plugin-go and release
Introduce new RPC methods with temporary type assertion check logic into terraform-plugin-mux and release
Introduce new RPC methods into other SDKs (terraform-plugin-sdk, terraform-plugin-framework) without type assertions and release
Copy temporary interface methods into existing interfaces in terraform-plugin-go and release (effectively making their implementations required)
Remove temporary type assertion check logic in terraform-plugin-mux and release
Remove temporary interfaces types in terraform-plugin-go and release
Provider developers in this model receive 6 or 7 dependency updates.
Consolidating this Go module's functionality into terraform-plugin-go would simplify this process for both maintainers and consumers, since there will be less dependency updates to consider overall:
Introduce temporary interface types for new RPCs into terraform-plugin-go and release
Introduce new RPC methods into other SDKs (terraform-plugin-sdk, terraform-plugin-framework) without type assertions and release
Move temporary interface methods into existing interfaces and remove temporary interfaces in terraform-plugin-go and release (effectively making their implementations required)
Provider developers in this model receive 3 or 4 dependency updates.
There are some tradeoffs however:
Metrics around mux usage will be slightly more difficult to calculate.
Increased time to release new features in terraform-plugin-go initially, but less time overall
Provider developers will likely need nudging to move to terraform-plugin-go's mux support, since terraform-plugin-mux will stop receiving updates and terraform-plugin-go will begin requiring implementation details not supported by the last version of terraform-plugin-mux.
Proposal
Decide if this Go module needs to be separate anymore. If so --
Lift and shift package code into terraform-plugin-go Go module, trying to make the migration a matter of only changing Go import statements.
github.com/hashicorp/terraform-plugin-mux/tf6to5server -> github.com/hashicorp/terraform-plugin-go/tfprotov6/tf6to5server (very debatable, real world usage needs to be determined)
Release terraform-plugin-go.
Add Go documentation deprecation comments to all exported functionality, pointing developers at the "new" Go module.
Add migration callouts to all pages of the mux website documentation.
Release terraform-plugin-go with published website support.
Update README and archive terraform-plugin-mux.
Potentially add web redirects from mux documentation to new location.
The maintainers should also determine if its worth actively promoting the necessary code changes to official/partner providers in the ecosystem, since this cohort is relatively small and staying up to date with available protocol features is relatively high impact effort.
terraform-plugin-mux version
Description
The creation of the terraform-plugin-mux Go module was a pragmatic, separate extension to the terraform-plugin-go ecosystem to enable provider developers to support multiple SDKs within a single logical provider. Later, functionality was added to enable the translation of protocol version 5 to version 6, so provider developers could opt into nested attribute support for new resource implementations but at the cost of only supporting more modern versions of Terraform (e.g. 1.x) since providers announce protocol support at the provider server level. The functionality in this Go module operates a low-to-the-protocol level, similar to that of terraform-plugin-go's provider server implementations.
While the separation of concerns and versioning between terraform-plugin-mux and terraform-plugin-go has the benefits of reducing friction for mux releases, there are a few considerations that were not clear or present when it was introduced:
hashicorp/aws), they may need this functionality for months or years. It does, however, represent an advanced use case and is generally temporary until the provider can afford a major version update. Some provider developers will instead skip the mux step by opting for wholesale migrating SDKs and do the major version update all at once because the temporary implementation and extra effort may not be worth it.The last point is the latest main driver for this considering this effort. Effectively and "safely" introducing protocol changes right now requires a dance of terraform-plugin-go and terraform-plugin-mux changes to prevent provider developers from needing to upgrade all their SDK dependencies at once, e.g.
Provider developers in this model receive 6 or 7 dependency updates.
Consolidating this Go module's functionality into terraform-plugin-go would simplify this process for both maintainers and consumers, since there will be less dependency updates to consider overall:
Provider developers in this model receive 3 or 4 dependency updates.
There are some tradeoffs however:
Proposal
Decide if this Go module needs to be separate anymore. If so --
github.com/hashicorp/terraform-plugin-mux/tf5muxserver->github.com/hashicorp/terraform-plugin-go/tfprotov5/tf5muxservergithub.com/hashicorp/terraform-plugin-mux/tf5to6server->github.com/hashicorp/terraform-plugin-go/tfprotov5/tf5to6servergithub.com/hashicorp/terraform-plugin-mux/tf6muxserver->github.com/hashicorp/terraform-plugin-go/tfprotov6/tf6muxservergithub.com/hashicorp/terraform-plugin-mux/tf6to5server->github.com/hashicorp/terraform-plugin-go/tfprotov6/tf6to5server(very debatable, real world usage needs to be determined)The maintainers should also determine if its worth actively promoting the necessary code changes to official/partner providers in the ecosystem, since this cohort is relatively small and staying up to date with available protocol features is relatively high impact effort.
References