pulumi-terraform-bridge

module
v3.84.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jun 4, 2024 License: Apache-2.0

README

Build Status Go Report Card GoDoc

Pulumi Terraform Bridge

This bridge adapts any Terraform Provider built using the Terraform Plugin SDK for use with Pulumi. The Terraform community provides resource providers that perform create, read, update, and delete (CRUD) operations for a broad array of infrastructure providers and types. In principle, any of them can be programmed using Pulumi with this bridge.

If you want to wrap a new Terraform provider as a Pulumi provider, check out pulumi/pulumi-tf-provider-boilerplate.

Developing a New Provider

The recommended way to start developing a new TF provider is with pulumi-tf-provider-boilerplate.

If you want details on how provider development works, please see our docs.

Upgrading an Existing Bridged Provider

To upgrade a provider that used to use the Terraform Plugin SDK to a version that uses the Terraform Plugin Framework, see here.

To upgrade a provider that was bridged from a Terraform provider built against Terraform Plugin SDK and you want to upgrade it to a version that has migrated some but not all resources/datasources to the Terraform Plugin Framework, see here.

Overview

Most users of Pulumi don't need to know how this bridge works. Many will find it interesting, and, if you'd like to bring up a new provider that is available in Terraform but not yet Pulumi, we would love to hear from you.

How It Works

There are two major things involved in this bridge: design-time and runtime.

At design-time, we code-generate packages by dynamic inspection of a Terraform Provider's schema. This only works for providers that are built using static schemas. It is possible to write Terraform Providers without this, which means the ability to create packages would not exist, but in practice all interesting providers use it.

Second, the bridge connects the Pulumi engine to a given Terraform Provider using Pulumi's RPC interfaces. This behavior also leverages the Terraform provider schema, for operations like performing validation and diffs.

Development

This section only matters if you want to build this bridge from scratch, or use it in your own project.

Prerequisites

Before doing any development, there are a few prerequisites to install:

Building and Testing

There is a Makefile in the root that builds and tests everything.

To build, ensure $GOPATH is set, and clone into a standard Go workspace:

$ git clone git@github.com:pulumi/pulumi-terraform-bridge $GOPATH/src/github.com/pulumi/pulumi-terraform-bridge
$ cd $GOPATH/src/github.com/pulumi/pulumi-terraform-bridge

You can run make to build and run tests:

$ make

This repo on its own isn't particularly interesting, until it is used to create a new Pulumi provider.

Releasing

See playbook.

Design Time Options

tfgen, the command that generates Pulumi schema/code for a bridged provider supports the following environment variables:

  • PULUMI_SKIP_MISSING_MAPPING_ERROR: If truthy, tfgen will not fail if a data source or resource in the TF provider is not mapped to the Pulumi provider. Instead, a warning is printed. Default is false.
  • PULUMI_SKIP_EXTRA_MAPPING_ERROR: If truthy, tfgen will not fail if a mapped data source or resource does not exist in the TF provider. Instead, warning is printed. Default is false.
  • PULUMI_MISSING_DOCS_ERROR: If truthy, tfgen will fail if docs cannot be found for a data source or resource. Default is false.
  • PULUMI_CONVERT: If truthy, tfgen will shell out to pulumi convert for converting example code from TF HCL to Pulumi PCL
  • PULUMI_CONVERT_ONLY: If set to a resource or data source ID such as "aws_acm_certificate" will convert docs only for that single resource; useful to speed up debugging docs issues
  • COVERAGE_OUTPUT_DIR: If set to a folder path, will generate a report on TF to Pulumi example code translation, including detailed errors and overall coverage statistics

Directories

Path Synopsis
internal
pkg
convert
Converts between Pulumi and Terraform value representations.
Converts between Pulumi and Terraform value representations.
tf2pulumi/internal/addrs
Package addrs contains types that represent "addresses", which are references to specific objects within a Terraform configuration or state.
Package addrs contains types that represent "addresses", which are references to specific objects within a Terraform configuration or state.
tf2pulumi/internal/config
The config package is responsible for loading and validating the configuration.
The config package is responsible for loading and validating the configuration.
tfbridge/info
[info] contains the types that bridged provider authors use to describe the mapping between Pulumi and Terraform providers.
[info] contains the types that bridged provider authors use to describe the mapping between Pulumi and Terraform providers.
tfbridge/x
Experimental extensions to the tfbridge module.
Experimental extensions to the tfbridge module.
tfgen
Facilities to help caching the example generation.
Facilities to help caching the example generation.
tfshim
Package tfshim implements an abstraction layer for TF bridge backends.
Package tfshim implements an abstraction layer for TF bridge backends.
tfshim/sdk-v2/internal/tf/configs/configschema
Code copied from https://github.com/hashicorp/terraform.git by go generate; DO NOT EDIT.
Code copied from https://github.com/hashicorp/terraform.git by go generate; DO NOT EDIT.
tfshim/sdk-v2/internal/tf/plans/objchange
Code copied from https://github.com/hashicorp/terraform.git by go generate; DO NOT EDIT.
Code copied from https://github.com/hashicorp/terraform.git by go generate; DO NOT EDIT.
A package that exposes an unstable interface across go module boundaries.
A package that exposes an unstable interface across go module boundaries.
scripts/exconverter
This script assists the rollout of the new example converter across bridged providers by computing the difference in example generation metrics.
This script assists the rollout of the new example converter across bridged providers by computing the difference in example generation metrics.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL