Skip to content

Latest commit

 

History

History
86 lines (59 loc) · 4.64 KB

new-provider.md

File metadata and controls

86 lines (59 loc) · 4.64 KB

Developing a New Provider

It is relatively easy to adapt a Terraform Provider, X, for use with Pulumi. The Cloudflare provider offers a good starting point for creating a new bridged provider.

You will create two Go binaries -- one purely for design-time usage to act as X's code-generator and the other for runtime usage to serve as its dynamic resource plugin -- and link with the Terraform Provider repo and this one. There is then typically a resources.go file that maps all of the Terraform Provider metadata available at runtime to types and concepts that the bridge will use to generate well-typed programmatic abstractions.

The Cloudflare provider provides a standard blueprint to follow for this. There are three major elements:

The Makefile compiles these programs, and notably, uses the resulting pulumi-tfgen-cloudflare binary to generate code for many different languages. The resulting generated code is stored in the sdk directory.

Building tfbridge.ProviderInfo

The main interaction point between the bridged provider authors and the bridge itself if via tfbridge.ProviderInfo.

Token Mapping

Each upstream Terraform resource needs to be given a Pulumi appropriate name, called a token. We call this process token mapping. A simple mapping looks like this:

			"aws_s3_bucket": {
				Tok: tfbridge.MakeResource(awsPackage, s3Mod, "Bucket"),
			},

Automatic Token Mapping

Mapping a couple of resources is fine, but it quickly becomes tiresome to provide a manual mapping for each resource and datasource in a large provider, especially since new updates to the provider introduce new resources and remove old resources. The solution is automatic token mappings.

For example:

prov.MustComputeTokens(tokens.SingleModule("docker_", "index",
	tokens.MakeStandard(dockerPkg)))

source

See automatic token mapping for more information.

Augmenting a Terraform Provider

To add new resources/datasources or replace existing resources/datasources to the bridge Terraform provider, see MuxWith.

Pulumi Bridge for Terraform Plugin Framework

For instructions on bridging a Terraform provider built using the Terraform Plugin Framework, please see New PF Provider.

Version Requirements

The pulumi-terraform-bridge depends on non-semver internals of pulumi/pulumi and on a fork of terraform-plugin-sdk/v2: github.com/pulumi/terraform-plugin-sdk/v2. You will need to match the version of both in your provider's go.mod file.

pulumi/pulumi

Keeping pulumi/pulumi at the right version is as simple as not manually upgrading the version of github.com/pulumi/pulumi/pkg/v3 and github.com/pulumi/pulumi/sdk/v3 required. When you upgrade your dependency on pulumi-terraform-bridge, it will pull in the version it needs, upgrading as necessary. We try to keep the version that the bridge uses in sync with the latest version of pulumi/pulumi.

github.com/pulumi/terraform-plugin-sdk/v2

You will need to add a replace directive to your provider/go.mod file that matches the one found in https://github.com/pulumi/pulumi-terraform-bridge/blob/master/go.mod. We don't change the version of github.com/pulumi/terraform-plugin-sdk/v2 very often, but when we do the bridge generally won't compile on the wrong version. Best practice is to check the SHA of the replace in the bridge uses and ensure that your replace matches. We know that this is annoying and would like to remove the fork requirement.