diff --git a/dynamic/README.md b/dynamic/README.md index fdafe6a6f..1bcf9bd1d 100644 --- a/dynamic/README.md +++ b/dynamic/README.md @@ -1,11 +1,10 @@ # Dynamic Bridged Provider -A *dynamically bridged provider* is a Pulumi provider parameterized by the identity of a terraform -provider. It consists of a binary `pulumi-terraform-bridge`, which is spun up as a provider by `pulumi`. The +A *dynamically bridged provider* is a Pulumi provider parameterized by the identity of a Terraform +provider. It consists of a binary `pulumi-terraform-provider`, which is spun up as a provider by `pulumi`. The binary is responsible for downloading the terraform provider it is emulating, then translating `pulumi`’s -[gRPC protocol](https://github.com/pulumi/pulumi/tree/master/proto/pulumi) into [Terraform’s v6 -protocol](https://developer.hashicorp.com/terraform/plugin/terraform-plugin-protocol). +[gRPC protocol](https://github.com/pulumi/pulumi/tree/master/proto/pulumi) into [Terraform’s v6 protocol](https://developer.hashicorp.com/terraform/plugin/terraform-plugin-protocol). ## Usage @@ -13,30 +12,28 @@ If you are using a language besides Pulumi YAML, you start by generating an SDK. ### SDK Generation -SDK generation relies on an existing terraform provider. The Terraform provider can be in a Terraform registry -(such as [OpenTofu's Registry](https://opentofu.org/docs/internals/provider-registry-protocol/)) or local to -your machine. +SDK generation relies on an existing Terraform provider. The Terraform provider can be in a Terraform registry +(such as [OpenTofu's Registry](https://opentofu.org/docs/internals/provider-registry-protocol/)) or local to your machine. #### Registry based SDK generation To generate an SDK based on a Terraform provider in a Terraform Registry, use: ``` sh -pulumi package gen-sdk terraform-bridge [hostname/][namespace/] [version] [--language ] +pulumi package gen-sdk terraform-provider [hostname/][namespace/] [version] [--language ] ``` -For example, to generate a Typescript SDK for [Azure's Alz -provider](https://github.com/Azure/terraform-provider-alz) at version v0.11.1, you would run: +For example, to generate a Typescript SDK for [Azure's Alz provider](https://github.com/Azure/terraform-provider-alz) at version v0.11.1, you would run: ``` sh -pulumi package gen-sdk --language typescript terraform-bridge registry.opentofu.org/Azure/alz 0.11.1 +pulumi package gen-sdk --language typescript terraform-provider registry.opentofu.org/Azure/alz 0.11.1 ``` At the time of writing, the latest version is `v0.11.1`, so you could drop the version: ``` patch --pulumi package gen-sdk --language typescript terraform-bridge registry.opentofu.org/Azure/alz 0.11.1 -+pulumi package gen-sdk --language typescript terraform-bridge registry.opentofu.org/Azure/alz +-pulumi package gen-sdk --language typescript terraform-provider registry.opentofu.org/Azure/alz 0.11.1 ++pulumi package gen-sdk --language typescript terraform-provider registry.opentofu.org/Azure/alz ``` If no version is specified, then the latest version is used. @@ -45,8 +42,8 @@ The default registry is `registry.opentofu.org`, so you can omit the registry as ``` patch --pulumi package gen-sdk --language typescript terraform-bridge registry.opentofu.org/Azure/alz -+pulumi package gen-sdk --language typescript terraform-bridge Azure/alz +-pulumi package gen-sdk --language typescript terraform-provider registry.opentofu.org/Azure/alz ++pulumi package gen-sdk --language typescript terraform-provider Azure/alz ``` The information you entered (with the registry and the version specified) are embedded in the generated SDK, @@ -57,14 +54,14 @@ so you won't need to enter any of this information again as long as you use the To generate an SDK based on a Terraform provider on your local file system, use: ``` sh -pulumi package gen-sdk terraform-bridge [path/]terraform-provider-[name] +pulumi package gen-sdk terraform-provider [path/]terraform-provider-[name] ``` The name of the provider must start with `terraform-provider-`. ## Architecture -The `pulumi-terraform-bridge` provider works by acquiring and running a Terraform provider, and then acting as +The `pulumi-terraform-provider` provider works by acquiring and running a Terraform provider, and then acting as a translation middleware between the Pulumi engine and the Terraform provider. A typical usage looks like this: @@ -72,7 +69,7 @@ A typical usage looks like this: ``` mermaid sequenceDiagram participant P as pulumi - create participant B as pulumi-terraform-bridge + create participant B as pulumi-terraform-provider P->>B: Run Pulumi Provider P->>B: Parameterize({name: "example", version: "v1.2.3"}) create participant T as terraform-provider-example @@ -93,7 +90,7 @@ sequenceDiagram B-->>P: Cancel done ``` -Diving deeper into how the repo is laid out, we see: +Diving deeper into how the repository is laid out, we see: ``` console ./ @@ -246,3 +243,32 @@ func ReadResourceRequest(i *tfprotov6.ReadResourceRequest) *tfplugin6.ReadResour } } ``` +## Releasing & [`pulumi/pulumi-terraform-provider`](https://github.com/pulumi/pulumi-terraform-provider) + +The `pulumi-terraform-provider` codebase is located in +[github.com/pulumi/pulumi-terraform-bridge/dynamic](https://github.com/pulumi/pulumi-terraform-bridge/blob/master/dynamic). However, the provider is released from +[github.com/pulumi/pulumi-terraform-provider](https://github.com/pulumi/pulumi-terraform-provider). There are 2 reasons for this: + +1. Pulumi's plugin discovery mechanism assumes that official plugins are located at + `github.com/pulumi/pulumi-${PLUGIN_NAME}`. If we want to use the plugin name `terraform-provider`, then the + canonical repository path is [github.com/pulumi/pulumi-terraform-provider/](https://github.com/pulumi/pulumi-terraform-provider/). + +2. [The registry](https://www.pulumi.com/registry) [expects](https://github.com/pulumi/registry/blob/39fc0592965e21a314a33c964db0a3e928c52aa4/tools/resourcedocsgen/cmd/pkgversion.go#L70-L91) each provider release to come from a repository with a semver tag: + `vX.Y.Z`. The bridge itself releases with those tags already, we would need to teach the registry to handle + nested tags. + +### Triggering a release + +To trigger a new release of `pulumi-terraform-provider`, push a new semver compatible tag to +`pulumi-terraform-provider. + +### Final repository structure + +The complexity of maintaining a separate release repository to have a separate release cycle is +sub-optimal. In the future, we should unify the release and code locations. We could either move the code to +`pulumi-terraform-provider` or move the release process into `pulumi-terraform-bridge`. + +Moving the release process into [github.com/pulumi/pulumi-terraform-bridge](https://github.com/pulumi/pulumi-terraform-bridge/blob/master/dynamic) would require: + +- [Provide a centralized lookup for PluginDownloadURL #4851 ](https://github.com/pulumi/registry/issues/4851) (with CLI adoption) +- [Support nested release labels #4852](https://github.com/pulumi/registry/issues/4852)