Skip to content

Commit 52b9447

Browse files
austinvalleaustinvalle
authored
Add terraform-plugin-mux@0.20.x documentation (#424)
1 parent fc0a509 commit 52b9447

File tree

7 files changed

+510
-0
lines changed

7 files changed

+510
-0
lines changed

‎content/terraform-plugin-mux/v0.20.x/data/plugin-mux-nav-data.json

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
[
2+
{
3+
"heading": "Combining and Translating"
4+
},
5+
{
6+
"title": "Overview",
7+
"path": ""
8+
},
9+
{
10+
"title": "Combining Protocol v5 Providers",
11+
"path": "combining-protocol-version-5-providers"
12+
},
13+
{
14+
"title": "Combining Protocol v6 Providers",
15+
"path": "combining-protocol-version-6-providers"
16+
},
17+
{
18+
"title": "Translating Protocol v5 to v6",
19+
"path": "translating-protocol-version-5-to-6"
20+
},
21+
{
22+
"title": "Translating Protocol v6 to v5",
23+
"path": "translating-protocol-version-6-to-5"
24+
}
25+
]

‎content/terraform-plugin-mux/v0.20.x/docs/plugin/mux/combining-protocol-version-5-providers.mdx

Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
---
2+
page_title: 'Plugin Development - Combining Protocol Version 5 Providers'
3+
description: >-
4+
Use the tf5muxserver package in terraform-plugin-mux to combine protocol version 5 providers.
5+
---
6+
7+
# Combining Protocol Version 5 Providers
8+
9+
The [`tf5muxserver`](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-mux/tf5muxserver) package enables combining any number of [protocol version 5 provider servers](/terraform/plugin/how-terraform-works#protocol-version-5) into a single server.
10+
11+
Use this package to:
12+
13+
* Support multiple development teams across separate codebases.
14+
* Support multiple provider SDK implementations. For example, you could downgrade an existing [terraform-plugin-framework](/terraform/plugin/framework) provider to protocol version 5 and then combine it with one or more providers built with [terraform-plugin-sdk/v2](/terraform/plugin/sdkv2).
15+
16+
## Compatibility
17+
18+
Protocol version 5 provider servers are compatible with Terraform CLI 0.12 and later.
19+
20+
The following provider server implementations are supported:
21+
22+
* [terraform-plugin-sdk/v2](/terraform/plugin/sdkv2): A higher-level SDK that makes Terraform provider development easier by abstracting implementation details.
23+
* [terraform-plugin-go tf5server](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-go/tfprotov5/tf5server): A lower-level SDK to develop Terraform providers for more advanced use cases.
24+
* [tf6to5server](/terraform/plugin/mux/translating-protocol-version-6-to-5): A package to translate protocol version 6 providers into protocol version 5.
25+
26+
## Requirements
27+
28+
To be combined, provider servers must meet the following requirements:
29+
30+
* All provider schemas (except block `MinItems`/`MaxItems`) must match.
31+
* All provider meta schemas must match.
32+
* Only one provider may implement each resource and data source.
33+
34+
If publishing to the [Terraform Registry](/terraform/registry), set `metadata.protocol_versions` to `["5.0"]` in the [Terraform Registry manifest file](/terraform/registry/providers/publishing#terraform-registry-manifest-file).
35+
36+
## Code Implementation
37+
38+
Use the [`tf5muxserver.NewMuxServer()`](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-mux/tf5muxserver#NewMuxServer) function to create a combined provider server. Most providers implement this method in the provider `main()` function of the root directory `main.go` file or within a shared internal package to enable [testing for the combined provider](#testing-implementation). You can use [`tf5server.WithManagedDebug()`](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-go/tfprotov5/tf5server#WithManagedDebug) to enable debugger support.
39+
40+
The following example implements `tf5muxserver.NewMuxServer()` in a `main()` function.
41+
42+
```go
43+
package main
44+
45+
import (
46+
"context"
47+
"flag"
48+
"log"
49+
50+
"github.com/example/terraform-provider-example/internal/provider1"
51+
"github.com/example/terraform-provider-example/internal/provider2"
52+
"github.com/example/terraform-provider-example/internal/framework_provider"
53+
"github.com/hashicorp/terraform-plugin-framework/providerserver"
54+
"github.com/hashicorp/terraform-plugin-go/tfprotov5"
55+
"github.com/hashicorp/terraform-plugin-go/tfprotov5/tf5server"
56+
"github.com/hashicorp/terraform-plugin-mux/tf5muxserver"
57+
)
58+
59+
var (
60+
// Version can be updated by goreleaser on release
61+
version string = "dev"
62+
)
63+
64+
func main() {
65+
debugFlag := flag.Bool("debug", false, "Start provider in debug mode.")
66+
flag.Parse()
67+
68+
ctx := context.Background()
69+
providers := []func() tfprotov5.ProviderServer{
70+
// Example terraform-plugin-sdk/v2 providers
71+
provider1.New(version)().GRPCProvider,
72+
provider2.New(version)().GRPCProvider,
73+
74+
// Example terraform-plugin-framework provider
75+
providerserver.NewProtocol5(
76+
framework_provider.New(version)(),
77+
),
78+
}
79+
80+
muxServer, err := tf5muxserver.NewMuxServer(ctx, providers...)
81+
82+
if err != nil {
83+
log.Fatal(err)
84+
}
85+
86+
var serveOpts []tf5server.ServeOpt
87+
88+
if *debugFlag {
89+
serveOpts = append(serveOpts, tf5server.WithManagedDebug())
90+
}
91+
92+
err = tf5server.Serve(
93+
"registry.terraform.io/example/example",
94+
muxServer.ProviderServer,
95+
serveOpts...,
96+
)
97+
98+
if err != nil {
99+
log.Fatal(err)
100+
}
101+
}
102+
```
103+
104+
## Testing Implementation
105+
106+
You can test individual providers using the same [acceptance tests](/terraform/plugin/testing/acceptance-tests) as before. Set the `ProtoV5ProviderFactories` field of `TestCase` with an instance of the mux server, instead of declaring the provider with other `TestCase` fields such as `ProviderFactories`.
107+
108+
The following example uses the acceptance testing framework to create a test for two providers.
109+
110+
```go
111+
resource.Test(t, resource.TestCase{
112+
// ... other TestCase fields ...
113+
ProtoV5ProviderFactories: map[string]func() (tfprotov5.ProviderServer, error) {
114+
"example": func() (tfprotov5.ProviderServer, error) {
115+
ctx := context.Background()
116+
providers := []func() tfprotov5.ProviderServer{
117+
// Example terraform-plugin-sdk/v2 providers
118+
provider1.New(version)().GRPCProvider,
119+
provider2.New(version)().GRPCProvider,
120+
121+
// Example terraform-plugin-framework provider
122+
providerserver.NewProtocol5(
123+
framework_provider.New(version)(),
124+
),
125+
}
126+
127+
muxServer, err := tf5muxserver.NewMuxServer(ctx, providers...)
128+
129+
if err != nil {
130+
return nil, err
131+
}
132+
133+
return muxServer.ProviderServer(), nil
134+
},
135+
},
136+
})
137+
```
138+
139+
Refer to the [acceptance tests](/terraform/plugin/testing/acceptance-tests) documentation for more details.

‎content/terraform-plugin-mux/v0.20.x/docs/plugin/mux/combining-protocol-version-6-providers.mdx

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
---
2+
page_title: 'Plugin Development - Combining Protocol Version 6 Providers'
3+
description: >-
4+
Use the tf6muxserver package in terraform-plugin-mux to combine protocol version 6 providers.
5+
---
6+
7+
# Combining Protocol Version 6 Providers
8+
9+
The [`tf6muxserver`](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-mux/tf6muxserver) package enables combining any number of [protocol version 6 provider servers](/terraform/plugin/how-terraform-works#protocol-version-6) into a single server.
10+
11+
Use this package to:
12+
13+
* Support multiple development teams across separate codebases.
14+
* Support multiple provider SDK implementations. For example, you could upgrade an existing [terraform-plugin-sdk/v2](/terraform/plugin/sdkv2) provider to protocol version 6 and then combine it with one or more providers built with [terraform-plugin-framework](/terraform/plugin/framework).
15+
16+
## Compatibility
17+
18+
Protocol version 6 provider servers are compatible with Terraform CLI 1.0 and later.
19+
20+
The following provider server implementations are supported:
21+
22+
* [terraform-plugin-framework](/terraform/plugin/framework): A higher-level SDK that makes Terraform provider development easier by abstracting implementation details.
23+
* [terraform-plugin-go tf6server](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-go/tfprotov6/tf6server): A lower-level SDK to develop Terraform providers for more advanced use cases.
24+
* [tf5to6server](/terraform/plugin/mux/translating-protocol-version-5-to-6): A package to translate protocol version 5 providers into protocol version 6.
25+
26+
## Requirements
27+
28+
To be combined, provider servers must meet the following requirements:
29+
30+
* All provider schemas must match.
31+
* All provider meta schemas must match.
32+
* Only one provider may implement each resource and data source.
33+
34+
If publishing to the [Terraform Registry](/terraform/registry), set `metadata.protocol_versions` to `["6.0"]` in the [Terraform Registry manifest file](/terraform/registry/providers/publishing#terraform-registry-manifest-file).
35+
36+
## Code Implementation
37+
38+
Use the [`tf6muxserver.NewMuxServer()`](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-mux/tf6muxserver#NewMuxServer) function to create a combined provider server. Most providers implement this in the provider `main()` function of the root directory `main.go` file or within a shared internal package to enable [testing for the combined provider](#testing-implementation). You can use [`tf6server.WithManagedDebug()`](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-go/tfprotov6/tf6server#WithManagedDebug) to enable debugger support.
39+
40+
The following example implements `tf6muxserver.NewMuxServer()` in a `main()` function.
41+
42+
```go
43+
package main
44+
45+
import (
46+
"context"
47+
"flag"
48+
"log"
49+
50+
"github.com/example/terraform-provider-example/internal/provider1"
51+
"github.com/example/terraform-provider-example/internal/provider2"
52+
"github.com/hashicorp/terraform-plugin-framework/tfsdk"
53+
"github.com/hashicorp/terraform-plugin-go/tfprotov6"
54+
"github.com/hashicorp/terraform-plugin-go/tfprotov6/tf6server"
55+
"github.com/hashicorp/terraform-plugin-mux/tf6muxserver"
56+
)
57+
58+
var (
59+
// Version can be updated by goreleaser on release
60+
version string = "dev"
61+
)
62+
63+
func main() {
64+
debugFlag := flag.Bool("debug", false, "Start provider in debug mode.")
65+
flag.Parse()
66+
67+
ctx := context.Background()
68+
providers := []func() tfprotov6.ProviderServer{
69+
// Example terraform-plugin-framework providers
70+
providerserver.NewProtocol6(provider1.New("test")())
71+
providerserver.NewProtocol6(provider2.New("test")())
72+
}
73+
74+
muxServer, err := tf6muxserver.NewMuxServer(ctx, providers...)
75+
76+
if err != nil {
77+
log.Fatal(err)
78+
}
79+
80+
var serveOpts []tf6server.ServeOpt
81+
82+
if *debugFlag {
83+
serveOpts = append(serveOpts, tf6server.WithManagedDebug())
84+
}
85+
86+
err = tf6server.Serve(
87+
"registry.terraform.io/example/example",
88+
muxServer.ProviderServer,
89+
serveOpts...,
90+
)
91+
92+
if err != nil {
93+
log.Fatal(err)
94+
}
95+
}
96+
```
97+
98+
## Testing Implementation
99+
100+
You can test individual providers using the same [acceptance tests](/terraform/plugin/testing/acceptance-tests) as before. Set the `ProtoV6ProviderFactories` field of `TestCase` with an instance of the mux server, instead of declaring the provider with other `TestCase` fields such as `ProviderFactories`.
101+
102+
The following example uses the acceptance testing framework to create a test for two providers.
103+
104+
```go
105+
resource.Test(t, resource.TestCase{
106+
// ... other TestCase fields ...
107+
ProtoV6ProviderFactories: map[string]func() (tfprotov6.ProviderServer, error) {
108+
"example": func() (tfprotov6.ProviderServer, error) {
109+
ctx := context.Background()
110+
providers := []func() tfprotov6.ProviderServer{
111+
// Example terraform-plugin-framework providers
112+
providerserver.NewProtocol6(provider1.New("test")())
113+
providerserver.NewProtocol6(provider2.New("test")())
114+
}
115+
116+
muxServer, err := tf6muxserver.NewMuxServer(ctx, providers...)
117+
118+
if err != nil {
119+
return nil, err
120+
}
121+
122+
return muxServer.ProviderServer(), nil
123+
},
124+
},
125+
})
126+
```
127+
128+
Refer to the [acceptance tests](/terraform/plugin/testing/acceptance-tests) documentation for more details.

‎content/terraform-plugin-mux/v0.20.x/docs/plugin/mux/index.mdx

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
---
2+
page_title: "Plugin Development - Combining and Translating Providers: Overview"
3+
description: >-
4+
Use terraform-plugin-mux to combine and translate providers. It minimizes code changes by wrapping existing provider servers.
5+
---
6+
7+
# Combining and Translating Providers
8+
9+
The [terraform-plugin-mux](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-mux) Go module is a collection of Go packages for combining (multiplexing) and translating provider servers. It helps minimize provider code changes by wrapping existing provider servers. This functionality is based on the [Terraform Plugin Protocol](/terraform/plugin/how-terraform-works#terraform-plugin-protocol) and [`terraform-plugin-go`](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-go) provider servers.
10+
11+
## Use Cases
12+
13+
The `terraform-plugin-mux` Go module enables flexibility when you develop and maintain Terraform providers. It is especially useful when you need to upgrade an existing provider to use the plugin framework SDK or the latest version of the plugin protocol. We recommend using `terraform-plugin-mux` for the following use cases:
14+
15+
- Combine providers to reduce maintenance burden while still supporting varying Terraform requirements or multiple provider SDK implementations.
16+
- Migrate resources and data sources from [terraform-plugin-sdk/v2](/terraform/plugin/sdkv2) to [terraform-plugin-framework](/terraform/plugin/framework) over time.
17+
- Develop with [terraform-plugin-sdk/v2](/terraform/plugin/sdkv2), but require Terraform CLI 1.0 or later.
18+
- Develop with [terraform-plugin-framework](/terraform/plugin/framework), but support Terraform CLI 0.12 or later.
19+
20+
## Combine Protocol 6 Providers
21+
22+
Use the [tf6muxserver](/terraform/plugin/mux/combining-protocol-version-6-providers) package to combine any number of [protocol version 6 provider servers](/terraform/plugin/how-terraform-works#protocol-version-6) into a single server.
23+
24+
## Combine Protocol 5 Providers
25+
26+
Use the [tf5muxserver](/terraform/plugin/mux/combining-protocol-version-5-providers) package to combine any number of [protocol version 5 provider servers](/terraform/plugin/how-terraform-works#protocol-version-5) into a single server.
27+
28+
## Translate Protocol 5 Providers to Protocol 6
29+
30+
Use the [tf5to6server](/terraform/plugin/mux/translating-protocol-version-5-to-6) package to translate a [protocol version 5 provider server](/terraform/plugin/how-terraform-works#protocol-version-5) into a [protocol version 6 provider server](/terraform/plugin/how-terraform-works#protocol-version-6).
31+
32+
## Translate Protocol 6 Providers to Protocol 5
33+
34+
Use the [tf6to5server](/terraform/plugin/mux/translating-protocol-version-6-to-5) package to translate a [protocol version 6 provider server](/terraform/plugin/how-terraform-works#protocol-version-6) into a [protocol version 5 provider server](/terraform/plugin/how-terraform-works#protocol-version-5).

0 commit comments

Comments
 (0)