From 604af454afbdb3534b8d588de32a4a371f3714f0 Mon Sep 17 00:00:00 2001 From: Ian Wahbe Date: Fri, 19 Apr 2024 15:51:58 +0200 Subject: [PATCH] Improve the instructions for bridging non sdkv2 providers The new instructions walk you through how to setup `xyz.New(version.Version)()` at the point where it is used. This will hopefully be clearer to our users. --- provider/resources.go | 125 +++++++++++++++++++++++++----------------- 1 file changed, 76 insertions(+), 49 deletions(-) diff --git a/provider/resources.go b/provider/resources.go index bd13513..25cea89 100644 --- a/provider/resources.go +++ b/provider/resources.go @@ -1,4 +1,4 @@ -// Copyright 2016-2023, Pulumi Corporation. +// Copyright 2016-2024, Pulumi Corporation. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. @@ -22,9 +22,7 @@ import ( "github.com/pulumi/pulumi-terraform-bridge/v3/pkg/tfbridge" "github.com/pulumi/pulumi-terraform-bridge/v3/pkg/tfbridge/tokens" - shim "github.com/pulumi/pulumi-terraform-bridge/v3/pkg/tfshim" shimv2 "github.com/pulumi/pulumi-terraform-bridge/v3/pkg/tfshim/sdk-v2" - "github.com/pulumi/pulumi/sdk/v3/go/common/resource" // Replace this provider with the provider you are bridging. xyz "github.com/iwahbe/terraform-provider-xyz/provider" @@ -41,32 +39,82 @@ const ( mainMod = "index" // the xyz module ) -// preConfigureCallback is called before the providerConfigure function of the underlying provider. -// It should validate that the provider can be configured, and provide actionable errors in the case -// it cannot be. Configuration variables can be read from `vars` using the `stringValue` function - -// for example `stringValue(vars, "accessKey")`. -func preConfigureCallback(resource.PropertyMap, shim.ResourceConfig) error { - return nil -} - //go:embed cmd/pulumi-resource-xyz/bridge-metadata.json var metadata []byte -// Provider returns additional overlaid schema and metadata associated with the provider.. +// Provider returns additional overlaid schema and metadata associated with the provider. func Provider() tfbridge.ProviderInfo { // Create a Pulumi provider mapping prov := tfbridge.ProviderInfo{ // Instantiate the Terraform provider - P: shimv2.NewProvider(xyz.New(version.Version)()), + // + // The [pulumi-terraform-bridge](https://github.com/pulumi/pulumi-terraform-bridge) supports 3 + // types of Terraform providers: + // + // 1. Providers written with the terraform-plugin-sdk/v1: + // + // If the provider you are bridging is written with the terraform-plugin-sdk/v1, then you + // will need to adapt the boilerplate: + // + // - Change the import "shimv2" to "shimv1" and change the associated import to + // "github.com/pulumi/pulumi-terraform-bridge/v3/pkg/tfshim/sdk-v1". + // + // You can then proceed as normal. + // + // 2. Providers written with terraform-plugin-sdk/v2: + // + // This boilerplate is already geared towards providers written with the + // terraform-plugin-sdk/v2, since it is the most common provider framework used. No + // adaptions are needed. + // + // 3. Providers written with terraform-plugin-framework: + // + // If the provider you are bridging is written with the terraform-plugin-framework, then + // you will need to adapt the boilerplate: + // + // - Remove the `shimv2` import and add: + // + // pfbridge "github.com/pulumi/pulumi-terraform-bridge/pf/tfbridge" + // + // - Replace `shimv2.NewProvider` with `pfbridge.ShimProvider`. + // + // - In provider/cmd/pulumi-tfgen-xyz/main.go, replace the + // "github.com/pulumi/pulumi-terraform-bridge/v3/pkg/tfgen" import with + // "github.com/pulumi/pulumi-terraform-bridge/pf/tfgen". Remove the `version.Version` + // argument to `tfgen.Main`. + // + // - In provider/cmd/pulumi-resource-xyz/main.go, replace the + // "github.com/pulumi/pulumi-terraform-bridge/v3/pkg/tfbridge" import with + // "github.com/pulumi/pulumi-terraform-bridge/pf/tfbridge". Replace the arguments to the + // `tfbridge.Main` so it looks like this: + // + // tfbridge.Main(context.Background(), "xyz", xyz.Provider(), + // tfbridge.ProviderMetadata{PulumiSchema: pulumiSchema}) + // + // Detailed instructions can be found at + // https://github.com/pulumi/pulumi-terraform-bridge/blob/master/pf/README.md#how-to-upgrade-a-bridged-provider-to-plugin-framework. + // After that, you can proceed as normal. + // + // This is where you give the bridge a handle to the upstream terraform provider. SDKv2 + // convention is to have a function at "github.com/iwahbe/terraform-provider-xyz/provider".New + // which takes a version and produces a factory function. The provider you are bridging may + // not do that. You will need to find the function (generally called in upstream's main.go) + // that produces a: + // + // - *"github.com/hashicorp/terraform-plugin-sdk/v2/helper/schema".Provider (for SDKv2) + // - *"github.com/hashicorp/terraform-plugin-sdk/v1/helper/schema".Provider (for SDKv1) + // - "github.com/hashicorp/terraform-plugin-framework/provider".Provider (for plugin-framework) + // + //nolint:lll + P: shimv2.NewProvider(xyz.New(version.Version)()), + Name: "xyz", Version: version.Version, - // DisplayName is a way to be able to change the casing of the provider - // name when being displayed on the Pulumi registry + // DisplayName is a way to be able to change the casing of the provider name when being + // displayed on the Pulumi registry DisplayName: "", - // The default publisher for all packages is Pulumi. - // Change this to your personal name (or a company name) that you - // would like to be shown in the Pulumi Registry if this package is published - // there. + // Change this to your personal name (or a company name) that you would like to be shown in + // the Pulumi Registry if this package is published there. Publisher: "abc", // LogoURL is optional but useful to help identify your package in the Pulumi Registry // if this package is published there. @@ -86,8 +134,8 @@ func Provider() tfbridge.ProviderInfo { License: "Apache-2.0", Homepage: "https://www.pulumi.com", Repository: "https://github.com/pulumi/pulumi-xyz", - // The GitHub Org for the provider - defaults to `terraform-providers`. Note that this - // should match the TF provider module's require directive, not any replace directives. + // The GitHub Org for the provider - defaults to `terraform-providers`. Note that this should + // match the TF provider module's require directive, not any replace directives. GitHubOrg: "", MetadataInfo: tfbridge.NewProviderMetadata(metadata), Config: map[string]*tfbridge.SchemaInfo{ @@ -100,26 +148,6 @@ func Provider() tfbridge.ProviderInfo { // }, // }, }, - PreConfigureCallback: preConfigureCallback, - Resources: map[string]*tfbridge.ResourceInfo{ - // Map each resource in the Terraform provider to a Pulumi type. Two examples - // are below - the single line form is the common case. The multi-line form is - // needed only if you wish to override types or other default options. - // - // "aws_iam_role": {Tok: tfbridge.MakeResource(mainPkg, mainMod, "IamRole")} - // - // "aws_acm_certificate": { - // Tok: tfbridge.MakeResource(mainPkg, mainMod, "Certificate"), - // Fields: map[string]*tfbridge.SchemaInfo{ - // "tags": {Type: tfbridge.MakeType(mainPkg, "Tags")}, - // }, - // }, - }, - DataSources: map[string]*tfbridge.DataSourceInfo{ - // Map each resource in the Terraform provider to a Pulumi function. An example - // is below. - // "aws_ami": {Tok: tfbridge.MakeDataSource(mainPkg, mainMod, "getAmi")}, - }, JavaScript: &tfbridge.JavaScriptInfo{ // List any npm dependencies and their versions Dependencies: map[string]string{ @@ -129,10 +157,6 @@ func Provider() tfbridge.ProviderInfo { "@types/node": "^10.0.0", // so we can access strongly typed node definitions. "@types/mime": "^2.0.0", }, - // See the documentation for tfbridge.OverlayInfo for how to lay out this - // section, or refer to the AWS provider. Delete this section if there are - // no overlay files. - //Overlay: &tfbridge.OverlayInfo{}, }, Python: &tfbridge.PythonInfo{ // List any Python dependencies and their version ranges @@ -156,12 +180,15 @@ func Provider() tfbridge.ProviderInfo { }, } - // These are new API's that you may opt to use to automatically compute resource - // tokens, and apply auto aliasing for full backwards compatibility. For more - // information, please reference: - // https://pkg.go.dev/github.com/pulumi/pulumi-terraform-bridge/v3/pkg/tfbridge#ProviderInfo.ComputeTokens + // MustComputeTokens maps all resources and datasources from the upstream provider into Pulumi. + // + // tokens.SingleModule puts every upstream item into your provider's main module. + // + // You shouldn't need to override anything, but if you do, use the [tfbridge.ProviderInfo.Resources] + // and [tfbridge.ProviderInfo.DataSources]. prov.MustComputeTokens(tokens.SingleModule("xyz_", mainMod, tokens.MakeStandard(mainPkg))) + prov.MustApplyAutoAliases() prov.SetAutonaming(255, "-")