diff --git a/pf/Makefile b/pf/Makefile deleted file mode 100644 index 647a9fd7e..000000000 --- a/pf/Makefile +++ /dev/null @@ -1,88 +0,0 @@ -TESTPARALLELISM := 10 -export PULUMI_DISABLE_AUTOMATIC_PLUGIN_ACQUISITION := true - -install_plugins:: - pulumi plugin install resource random 4.16.3 - -build.tests:: install_plugins - go test -test.run NONE - cd tests && go test -test.run NONE - cd tests/integration && go test -test.run NONE - -test:: test.unit test.integration - -test.unit:: - go test -v -count=1 -cover -coverpkg=./... -coverprofile ./coverage.out -timeout 2h -parallel ${TESTPARALLELISM} ./... - cd tests && go test -v -count=1 -cover -coverpkg=./... -coverprofile ./coverage.out -timeout 2h -parallel ${TESTPARALLELISM} # tests have a separte go.mod - -test.integration:: - cd tests/integration && go test -v -count=1 -timeout 2h -parallel ${TESTPARALLELISM} - -test.cover:: - cd tests && go test -cover -coverpkg=github.com/pulumi/pulumi-terraform-bridge/pf/tfbridge -coverprofile=cover.out - go tool cover -html=tests/cover.out - -build:: - go build -v all - cd tests && go build -v all - cd tests/integration && go build -v all - -build.testproviders:: \ - tests/bin/pulumi-resource-testbridge \ - tests/bin/pulumi-resource-random \ - tests/bin/pulumi-resource-tls \ - tests/bin/pulumi-resource-muxedrandom - -tests/bin/pulumi-resource-random:: tests/bin/pulumi-tfgen-random - ./tests/bin/pulumi-tfgen-random schema --out tests/internal/testprovider/cmd/pulumi-resource-random/ - rm tests/internal/testprovider/cmd/pulumi-resource-random/Pulumi.yaml - (cd tests/internal/testprovider/cmd/pulumi-resource-random && go build -o ../../../../bin/) - -tests/bin/pulumi-tfgen-random:: - mkdir -p tests/bin - echo '{}' > tests/internal/testprovider/cmd/pulumi-resource-random/bridge-metadata.json - (cd tests/internal/testprovider/cmd/pulumi-tfgen-random && go build -o ../../../../bin/) - -tests/bin/pulumi-resource-tls:: tests/bin/pulumi-tfgen-tls - ./tests/bin/pulumi-tfgen-tls schema --out tests/internal/testprovider/cmd/pulumi-resource-tls/ - rm tests/internal/testprovider/cmd/pulumi-resource-tls/Pulumi.yaml - (cd tests/internal/testprovider/cmd/pulumi-resource-tls && go build -o ../../../../bin/) - -tests/bin/pulumi-tfgen-tls:: - mkdir -p tests/bin - echo '{}' > tests/internal/testprovider/cmd/pulumi-resource-tls/bridge-metadata.json - (cd tests/internal/testprovider/cmd/pulumi-tfgen-tls && go build -o ../../../../bin/) - -tests/bin/pulumi-resource-testbridge:: tests/bin/pulumi-tfgen-testbridge - ./tests/bin/pulumi-tfgen-testbridge schema --out tests/internal/testprovider/cmd/pulumi-resource-testbridge/ - rm tests/internal/testprovider/cmd/pulumi-resource-testbridge/Pulumi.yaml - (cd tests/internal/testprovider/cmd/pulumi-resource-testbridge && go build -o ../../../../bin/) - -tests/bin/pulumi-tfgen-testbridge:: - mkdir -p tests/bin - echo '{}' > tests/internal/testprovider/cmd/pulumi-resource-testbridge/bridge-metadata.json - (cd tests/internal/testprovider/cmd/pulumi-tfgen-testbridge && go build -o ../../../../bin/) - -tests/bin/pulumi-resource-muxedrandom:: tests/bin/pulumi-tfgen-muxedrandom - ./tests/bin/pulumi-tfgen-muxedrandom schema --out tests/internal/testprovider/cmd/pulumi-resource-muxedrandom/ - rm tests/internal/testprovider/cmd/pulumi-resource-muxedrandom/Pulumi.yaml - (cd tests/internal/testprovider/cmd/pulumi-resource-muxedrandom && go build -o ../../../../bin/) - -tests/bin/pulumi-tfgen-muxedrandom:: - mkdir -p tests/bin - echo '{}' > tests/internal/testprovider/cmd/pulumi-resource-muxedrandom/bridge-metadata.json - (cd tests/internal/testprovider/cmd/pulumi-tfgen-muxedrandom && go build -o ../../../../bin/) - -gen.testdata:: - (cd tests/testdatagen/genrandom && ./generate.sh) - -.PHONY: test tidy - -tidy:: - go mod tidy - cd tests && go mod tidy - cd tests/internal/randomshim && go mod tidy - cd tests/internal/tlsshim && go mod tidy - cd tests/testdatagen/genrandom && go mod tidy - -.PHONY: todos diff --git a/pf/README.md b/pf/README.md index 54a9992f8..e7efe0a37 100644 --- a/pf/README.md +++ b/pf/README.md @@ -1,233 +1,2 @@ -# Pulumi Bridge for Terraform Plugin Framework - -This bridge enables creating [Pulumi Resource -providers](https://www.pulumi.com/docs/intro/concepts/resources/providers/) from [Terraform -Providers](https://github.com/terraform-providers) built using the [Terraform Plugin -Framework](https://developer.hashicorp.com/terraform/plugin/framework). - -If you need to adapt [Terraform Plugin SDK](https://github.com/hashicorp/terraform-plugin-sdk) based -providers, see [the documentation for bridging a new SDK based provider](../docs/new-provider.md). - -If you have a Pulumi provider that was bridged from a Terraform provider built against [Terraform Plugin -SDK](https://github.com/hashicorp/terraform-plugin-sdk) and you want to upgrade it to a version that has -migrated some but not all resources/datasources to the [Plugin -Framework](https://github.com/hashicorp/terraform-plugin-sdk?tab=readme-ov-file), see -[here](../docs/upgrade-sdk-to-mux.md). - -## How to Bridge a Provider - -Follow these steps to bridge a Terraform Provider to Pulumi. - -1. You will need a Provider value from the `github.com/hashicorp/terraform-plugin-framework/provider` package. You can - build it yourself as part of developing a Terraform Provider, or find it in published Terraform sources. - - For example, `terraform-provider-random` - [exposes](https://github.com/hashicorp/terraform-provider-random/blob/main/internal/provider/provider.go#L13) a `func - New() provider.Provider` call. Since this definition lives in an `internal` package it cannot easily be referenced in - an external Go project, but it is still possible to reference it using Go linker tricks. See - `tests/internal/randomshim/shim.go` for a full example. - -2. Populate a `ProviderInfo` struct, mapping Terraform resource names to Pulumi tokens. Replace `myprovider` with your - provider name. - - ```go - package myprovider - - import ( - _ "embed" - "github.com/hashicorp/terraform-plugin-framework/provider" - pf "github.com/pulumi/pulumi-terraform-bridge/pf/tfbridge" - "github.com/pulumi/pulumi-terraform-bridge/v3/pkg/tfbridge" - ) - - //go:embed cmd/pulumi-resource-myprovider/bridge-metadata.json - var bridgeMetadata []byte - - func MyProvider() tfbridge.ProviderInfo { - info := tfbridge.ProviderInfo{ - P: pf.ShimProvider(), - Name: "myprovider", - Version: "1.2.3", - Resources: map[string]*tfbridge.ResourceInfo{ - "myresource": {Tok: "myprovider::MyResource"}, - }, - MetadataInfo: tfbridge.NewProviderMetadata(bridgeMetadata), - } - return info - } - ``` - -3. Build a `pulumi-tfgen-myprovider` binary. - - ```go - package main - - import ( - "github.com/pulumi/pulumi-terraform-bridge/pf/tfgen" - // import myprovider - ) - - func main() { - tfgen.Main("myprovider", myprovider.MyProvider()) - } - ``` - -4. Generate a [Pulumi Package Schema](https://www.pulumi.com/docs/guides/pulumi-packages/schema/) and bridge metadata. - - ```bash - mkdir -p ./schema - pulumi-tfgen-myprovider schema --out ./schema - jq . ./schema/schema.json - jq . ./schema/bridge-metadata.json - ``` - -5. Build the Pulumi provider binary `pulumi-resource-myprovider`, embedding the generated `schema.json` and - `bridge-metadata.json` from Step 4. - - ```go - package main - - import ( - "context" - _ "embed" - - "github.com/pulumi/pulumi-terraform-bridge/pf/tfbridge" - // import myprovider - ) - - //go:embed schema.json - var schema []byte - - func main() { - meta := tfbridge.ProviderMetadata{PackageSchema: schema} - tfbridge.Main(context.Background(), "myprovider", myprovider.MyProvider(), meta) - } - ``` - -6. To try out the provider, place `pulumi-resource-myprovider` in PATH and create a new Pulumi YAML project to - instantiate the provider's resources, and run `pulumi up` on that project: - - ``` - name: basicprogram - runtime: yaml - resources: - r1: - type: myprovider::MyResource - properties: - prop1: x - prop2: y - ``` - -7. If you want to test using the provider from other languages such as TypeScript, you can generate the SDKs for each - language by running `pulumi-tfgen-myprovider` binary (see `--help` for all the options). - - -## How to Upgrade a Bridged Provider to Plugin Framework - -Follow these steps if you have a Pulumi provider that was bridged from a Terraform provider built against [Terraform -Plugin SDK](https://github.com/hashicorp/terraform-plugin-sdk) and you want to upgrade it to a version that has migrated -to the Plugin Framework. - -1. Ensure you have access to the github.com/hashicorp/terraform-plugin-framework/provider.Provider from the upstream provider. - Make sure the module is now depending on "github.com/hashicorp/terraform-plugin-framework" instead of "github.com/hashicorp/terraform-plugin-sdk/v2". - If the provider is shimmed (or needs to be), update the source code accordingly. For example, a `shim.go` that looked like this: - - ```go - package shim - - import ( - "github.com/hashicorp/terraform-plugin-sdk/v2/helper/schema" - "github.com/terraform-providers/terraform-provider-tls/internal/provider" - ) - - func NewProvider() *schema.Provider { - p, _ := provider.New() - return p - } - ``` - - Becomes: - - ```go - package shim - - import ( - "github.com/hashicorp/terraform-plugin-framework/provider" - p "github.com/hashicorp/terraform-provider-tls/internal/provider" - ) - - func NewProvider() provider.Provider { - return p.New() - } - ``` - - Make sure the module builds: - - ``` - cd provider/shim - go mod tidy - go build - ``` - -2. Find tfgen binary `main` that calls `tfgen.Main` from `github.com/pulumi/pulumi-terraform-bridge/v3/pkg/tfgen` - and update it to call `tfgen.Main` from `github.com/pulumi/pulumi-terraform-bridge/pf/tfgen`. - - Note that the extra verson parameter is removed from `tfgen.Main`, so this code: - - ```go - tfgen.Main("tls", version.Version, tls.Provider()) - ``` - - Becomes: - - ``` - tfgen.Main("tls", tls.Provider()) - ``` - -3. Find the provider binary `main` that calls `tfbridge.Main` from - `github.com/pulumi/pulumi-terraform-bridge/v3/pkg/tfbridge` and update it to `Main` from - `github.com/pulumi/pulumi-terraform-bridge/pf/tfbridge`. Note the signature changes: version parameter is removed, - `Context` is now required, and there is a new `bridge-metadata.json` blob that needs to be embedded: - - ```go - ... - - func main() { - meta := tfbridge.ProviderMetadata{PackageSchema: schema} - tfbridge.Main(context.Background(), "myprovider", myprovider.MyProvider(), meta) - } - ``` - -4. Update code declaring `tfbridge.ProviderInfo` (typically in `provider/resources.go`): - - ```go - - //go:embed cmd/pulumi-resource-myprovider/bridge-metadata.json - var bridgeMetadata []byte - - func Provider() tfbridge.ProviderInfo { - info := tfbridge.ProviderInfo{ - // Replace P (abbreviated for Provider): - P: pf.ShimProvider(shim.NewProvider()). - - // Make sure Version is set, as it is now required. - Version: ..., - - // This is now required. - MetadataInfo: tfbridge.NewProviderMetadata(bridgeMetadata), - - // Keep the rest of the code as before. - } - return info - } - ``` - -5. From this point the update proceeds as a typical upstream provider update. Build and run the tfgen binary to compute - the Pulumi Package Schema. It will now also compute a new metadata file `bridge-metadata.json`, build the provider - binary, re-generate language-specific SDKs and run tests. - - ``` - make tfgen - make provider - make build_sdks - ``` +> ![IMPORTANT] +> This module has been deprecated. Please use `github.com/pulumi/pulumi-terraform-bridge/v3/pkg/pf` instead.