commit	f8ddc4c1094e0f994e94e285f132c243772e6c33	[log] [tgz]
author	dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	Tue Apr 08 10:28:52 2025 +0100
committer	GitHub <noreply@github.com>	Tue Apr 08 10:28:52 2025 +0100
tree	b8bf50457cce4fab1077aae1e12aa0ff581cf014
parent	d17c7eef514dadd496e7609d8b67d5a9df3290cb [diff]

tree: b8bf50457cce4fab1077aae1e12aa0ff581cf014

README.md

terraform-exec

A Go module for constructing and running Terraform CLI commands. Structured return values use the data types defined in terraform-json.

The Terraform Plugin Framework is the canonical Go interface (SDK) for Terraform plugins using the gRPC protocol. This library is intended for use in Go programs that make use of Terraform's other interface, the CLI. Importing this library is preferable to importing github.com/hashicorp/terraform/command, because the latter is not intended for use outside Terraform Core.

While terraform-exec is already widely used, please note that this module is not yet at v1.0.0, and that therefore breaking changes may occur in minor releases.

We strictly follow semantic versioning.

Go compatibility

This library is built in Go, and uses the support policy of Go as its support policy. The two latest major releases of Go are supported by terraform-exec.

Currently, that means Go 1.23 or later must be used.

Terraform compatibility

We generally follow Terraform's own compatibility promises. i.e. we recommend Terraform v1.x to be used alongside this library.

Given the nature of this library being used in automation, we maintain compatibility on best effort basis with latest minor versions from 0.12 and later. This does not imply coverage of all features or CLI surface, just that it shouldn't break in unexpected ways.

Usage

The Terraform struct must be initialised with NewTerraform(workingDir, execPath).

Top-level Terraform commands each have their own function, which will return either error or (T, error), where T is a terraform-json type.

Example

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/hashicorp/go-version"
	"github.com/hashicorp/hc-install/product"
	"github.com/hashicorp/hc-install/releases"
	"github.com/hashicorp/terraform-exec/tfexec"
)

func main() {
	installer := &releases.ExactVersion{
		Product: product.Terraform,
		Version: version.Must(version.NewVersion("1.0.6")),
	}

	execPath, err := installer.Install(context.Background())
	if err != nil {
		log.Fatalf("error installing Terraform: %s", err)
	}

	workingDir := "/path/to/working/dir"
	tf, err := tfexec.NewTerraform(workingDir, execPath)
	if err != nil {
		log.Fatalf("error running NewTerraform: %s", err)
	}

	err = tf.Init(context.Background(), tfexec.Upgrade(true))
	if err != nil {
		log.Fatalf("error running Init: %s", err)
	}

	state, err := tf.Show(context.Background())
	if err != nil {
		log.Fatalf("error running Show: %s", err)
	}

	fmt.Println(state.FormatVersion) // "0.1"
}

Testing Terraform binaries

The terraform-exec test suite contains end-to-end tests which run realistic workflows against a real Terraform binary using tfexec.Terraform{}.

To run these tests with a local Terraform binary, set the environment variable TFEXEC_E2ETEST_TERRAFORM_PATH to its path and run:

go test -timeout=20m ./tfexec/internal/e2etest

For more information on terraform-exec's test suite, please see Contributing below.

Contributing

Please see CONTRIBUTING.md.