https://github.com/hashicorp/terraform-exec

Terraform CLI commands via Go.
https://github.com/hashicorp/terraform-exec

go terraform terraform-sdk

Last synced: 5 days ago
JSON representation

Terraform CLI commands via Go.

• Host: GitHub
• URL: https://github.com/hashicorp/terraform-exec
• Owner: hashicorp
• License: mpl-2.0
• Created: 2020-04-30T17:17:52.000Z (over 4 years ago)
• Default Branch: main
• Last Pushed: 2025-01-06T11:01:44.000Z (19 days ago)
• Last Synced: 2025-01-08T13:07:31.900Z (17 days ago)
• Topics: go, terraform, terraform-sdk
• Language: Go
• Homepage: https://pkg.go.dev/github.com/hashicorp/terraform-exec
• Size: 771 KB
• Stars: 696
• Watchers: 16
• Forks: 116
• Open Issues: 78
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGELOG.md
  • Contributing: CONTRIBUTING.md
  • License: LICENSE
  • Codeowners: .github/CODEOWNERS

Awesome Lists containing this project

• awesome-repositories - hashicorp/terraform-exec - Terraform CLI commands via Go. (Go)

README

        
[![PkgGoDev](https://pkg.go.dev/badge/github.com/hashicorp/terraform-exec)](https://pkg.go.dev/github.com/hashicorp/terraform-exec)

# terraform-exec

A Go module for constructing and running [Terraform](https://terraform.io) CLI commands. Structured return values use the data types defined in [terraform-json](https://github.com/hashicorp/terraform-json).

The [Terraform Plugin Framework](https://github.com/hashicorp/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](https://semver.org).

## Go compatibility

This library is built in Go, and uses the [support policy](https://golang.org/doc/devel/release.html#policy) of Go as its support policy. The two latest major releases of Go are supported by terraform-exec.

Currently, that means Go **1.18** or later must be used.

## 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

```go

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:

```sh

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](./CONTRIBUTING.md).