terraform-exec

A Go module for constructing and runningTerraform CLI commands. Structured return values use the data types defined interraform-json.

TheTerraform 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 importinggithub.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 isnot yet at v1.0.0, and that therefore breaking changes may occur in minor releases.

We strictly followsemantic versioning.

Go compatibility

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

Currently, that means Go1.23 or later must be used.

Terraform compatibility

We generally followTerraform'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 compatibilityon best effort basis with latest minor versions from0.12 and later. This does not imply coverage of all features or CLI surface, just that it shouldn't break in unexpected ways.

Usage

TheTerraform struct must be initialised withNewTerraform(workingDir, execPath).

Top-level Terraform commands each have their own function, which will return eithererror or(T, error), whereT is aterraform-json type.

Example

package mainimport ("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 usingtfexec.Terraform{}.

To run these tests with a local Terraform binary, set the environment variableTFEXEC_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 seeCONTRIBUTING.md.