DOCSEARCHbyAlgolia
Submit Docs

terraform-exec

repository·main·Indexed 21 days ago

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

A Go module for programmatically constructing and executing Terraform CLI commands. It provides structured return values using terraform-json types, allowing automation tools to interact with the Terraform CLI. Supports Go 1.24+ and maintains best-effort compatibility with Terraform versions 0.12 and later, with v1.x recommended.

Tokens
979
Snippets
3
Records
4
Agent score
24%

What's inside terraform-exec

  1. Run terraform-exec end-to-end tests locally

    main

    The terraform-exec test suite uses end-to-end tests that run against a real Terraform binary. To run these tests using a local Terraform installation, set the TFEXEC_E2ETEST_TERRAFORM_PATH environment variable to the path of your binary and execute the test command.

    export TFEXEC_E2ETEST_TERRAFORM_PATH=/path/to/your/terraform
go test -timeout=20m ./tfexec/internal/e2etest

  2. Run Terraform commands in Go

    main

    The library provides programmatic access to Terraform CLI commands. Commands like Init or Show are called with a context.Context. Some commands accept functional options (e.g., tfexec.Upgrade(true)) to modify behavior.

    Example workflow:

    1. Initialize the tfexec.Terraform instance.
    2. Run tf.Init to initialize the working directory.
    3. Run commands like tf.Show to retrieve structured state data.
    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"
}

  3. Initialize terraform-exec with NewTerraform

    main

    To use terraform-exec, you must initialize a Terraform struct using the tfexec.NewTerraform function. This function requires two arguments:

    1. workingDir: The directory where your Terraform configuration files are located.
    2. execPath: The absolute path to the Terraform CLI binary.

    Top-level Terraform commands are provided as functions on this struct. Depending on the command, they return either a simple error or a tuple of (T, error), where T is a data type defined in the terraform-json repository.

    tf, err := tfexec.NewTerraform(workingDir, execPath)

  4. Compatibility requirements for terraform-exec

    main

    Go Compatibility

    terraform-exec follows the Go support policy. It supports the two latest major releases of Go. Currently, you must use Go 1.24 or later.

    Terraform Compatibility

    • Recommended: Terraform v1.x.
    • Supported Range: The library maintains best-effort compatibility with Terraform versions from 0.12 and later. Note that this does not guarantee coverage of every CLI feature or surface, but ensures stability for automation.