Terraform Cloud/Enterprise Go Client

The official Go API client for Terraform Cloud/Enterprise.

This client supports the Terraform Cloud V2 API. As Terraform Enterprise is a self-hosted distribution of Terraform Cloud, this client supports both Cloud and Enterprise use cases. In all package documentation and API, the platform will always be stated as 'Terraform Enterprise' - but a feature will be explicitly noted as only supported in one or the other, if applicable (rare).

Version Information

Almost always, minor version changes will indicate backwards-compatible features and enhancements. Occasionally, function signature changes that reflect a bug fix may appear as a minor version change. Patch version changes will be used for bug fixes, performance improvements, and otherwise unimpactful changes.

Example Usage

Construct a new TFE client, then use the various endpoints on the client to access different parts of the Terraform Enterprise API. The following example lists all organizations.

(Recommended Approach) Using custom config to provide configuration details to the API client

import (
  "context"
  "log"

  "github.com/hashicorp/go-tfe"
)

config := &tfe.Config{
	Address: "https://tfe.local",
	Token: "insert-your-token-here",
  RetryServerErrors: true,
}

client, err := tfe.NewClient(config)
if err != nil {
	log.Fatal(err)
}

orgs, err := client.Organizations.List(context.Background(), nil)
if err != nil {
	log.Fatal(err)
}

Using the default config with env vars

The default configuration makes use of the TFE_ADDRESS and TFE_TOKEN environment variables.

TFE_ADDRESS - URL of a Terraform Cloud or Terraform Enterprise instance. Example: https://tfe.local
TFE_TOKEN - An API token for the Terraform Cloud or Terraform Enterprise instance.

Note: Alternatively, you can set TFE_HOSTNAME which serves as a fallback for TFE_ADDRESS. It will only be used if TFE_ADDRESS is not set and will resolve the host to an https scheme. Example: tfe.local => resolves to https://tfe.local

The environment variables are used as a fallback to configure TFE client if the Address or Token values are not provided as in the cases below:

Using the default configuration

import (
  "context"
  "log"

  "github.com/hashicorp/go-tfe"
)

// Passing nil to tfe.NewClient method will also use the default configuration
client, err := tfe.NewClient(tfe.DefaultConfig())
if err != nil {
	log.Fatal(err)
}

orgs, err := client.Organizations.List(context.Background(), nil)
if err != nil {
	log.Fatal(err)
}

When Address or Token has no value

import (
  "context"
  "log"

  "github.com/hashicorp/go-tfe"
)

config := &tfe.Config{
	Address: "",
	Token: "",
}

client, err := tfe.NewClient(config)
if err != nil {
	log.Fatal(err)
}

orgs, err := client.Organizations.List(context.Background(), nil)
if err != nil {
	log.Fatal(err)
}

Documentation

For complete usage of the API client, see the full package docs.

API Coverage

This API client covers most of the existing Terraform Cloud API calls and is updated regularly to add new or missing endpoints.

Examples

See the examples directory.

Running tests

See TESTS.md.

Issues and Contributing

See CONTRIBUTING.md

Releases

See RELEASES.md

hashicorp/go-tfe

hashicorp

Reviews

Repository Details