Terraform Enterprise Go Client

This is an API client for Terraform Enterprise.

NOTE

The Terraform Enterprise API endpoints are in beta and are subject to change! So that means this API client is also in beta and is also subject to change. We will indicate any breaking changes by releasing new versions. Until the release of v1.0, any minor version changes will indicate possible breaking changes. Patch version changes will be used for both bugfixes and non-breaking changes.

Coverage

Currently the following endpoints are supported:

• Accounts
• Applies
• Configuration Versions
• Cost Estimates
• IP Ranges
• Notification Configurations
• OAuth Clients
• OAuth Tokens
• Organizations
• Organization Memberships
• Organization Tokens
• Plan Exports
• Plans
• Policies
• Policy Checks
• Policy Sets
• Policy Set Parameters
• Policy Checks
• Registry Modules
• Runs
• Run Triggers
• SSH Keys
• State Versions
• State Version Outputs
• Team Access
• Team Memberships
• Team Tokens
• Teams
• User Tokens
• Users
• [DEPRECATED] Variables
• Workspaces
• Workspace Variables
• Admin

Installation

Installation can be done with a normal go get:

go get -u github.com/hashicorp/go-tfe

Documentation

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

Usage

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

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

config := &tfe.Config{
	Token: "insert-your-token-here",
}

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

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

Examples

The examples directory contains a couple of examples. One of which is listed here as well:

package main

import (
	"log"

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

func main() {
	config := &tfe.Config{
		Token: "insert-your-token-here",
	}

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

	// Create a context
	ctx := context.Background()

	// Create a new organization
	options := tfe.OrganizationCreateOptions{
		Name:  tfe.String("example"),
		Email: tfe.String("info@example.com"),
	}

	org, err := client.Organizations.Create(ctx, options)
	if err != nil {
		log.Fatal(err)
	}

	// Delete an organization
	err = client.Organizations.Delete(ctx, org.Name)
	if err != nil {
		log.Fatal(err)
	}
}

Running tests

1. (Optional) Create repositories for policy sets and registry modules

If you are planning to run the full suite of tests or work on policy sets or registry modules, you'll need to set up repositories for them in GitHub.

Your policy set repository will need the following:

1. A policy set stored in a subdirectory policy-sets/foo
2. A branch other than master named policies

Your registry module repository will need to be a valid module. It will need the following:

1. To be named terraform-<PROVIDER>-<NAME>
2. At least one valid SemVer tag in the format x.y.z terraform-random-module is a good example repo.

2. Set up environment variables

Required:

Tests are run against an actual backend so they require a valid backend address and token.

1. TFE_ADDRESS - URL of a Terraform Cloud or Terraform Enterprise instance to be used for testing, including scheme. Example: https://tfe.local
2. TFE_TOKEN - A user API token for the Terraform Cloud or Terraform Enterprise instance being used for testing.

Optional:

1. GITHUB_TOKEN - GitHub personal access token. Required for running any tests that use VCS (OAuth clients, policy sets, etc).
2. GITHUB_POLICY_SET_IDENTIFIER - GitHub policy set repository identifier in the format username/repository. Required for running policy set tests.
3. GITHUB_REGISTRY_MODULE_IDENTIFIER - GitHub registry module repository identifier in the format username/repository. Required for running registry module tests.

You can set your environment variables up however you prefer. The following are instructions for setting up environment variables using envchain.

1. Make sure you have envchain installed. Instructions for this can be found in the envchain README.

2. Pick a namespace for storing your environment variables. I suggest go-tfe or something similar.

3. For each environment variable you need to set, run the following command:

   envchain --set YOUR_NAMESPACE_HERE ENVIRONMENT_VARIABLE_HERE

   OR

   Set all of the environment variables at once with the following command:

   envchain --set YOUR_NAMESPACE_HERE TFE_ADDRESS TFE_TOKEN GITHUB_TOKEN GITHUB_POLICY_SET_IDENTIFIER

3. Make sure run queue settings are correct

In order for the tests relating to queuing and capacity to pass, FRQ (fair run queuing) should be enabled with a limit of 2 concurrent runs per organization on the Terraform Cloud or Terraform Enterprise instance you are using for testing.

4. Run the tests

Running all the tests

As running the all of the tests takes about ~20 minutes, make sure to add a timeout to your command (as the default timeout is 10m).

With envchain:

$ envchain YOUR_NAMESPACE_HERE go test ./... -timeout=30m

Without envchain:

$ go test ./... -timeout=30m

Running specific tests

The commands below use notification configurations as an example.

With envchain:

$ envchain YOUR_NAMESPACE_HERE go test -run TestNotificationConfiguration -v ./...

Without envchain:

$ go test -run TestNotificationConfiguration -v ./...

Issues and Contributing

If you find an issue with this package, please report an issue. If you'd like, we welcome any contributions. Fork this repository and submit a pull request.

Releases

Documentation updates and test fixes that only touch test files don't require a release or tag. You can just merge these changes into master once they have been approved.

Creating a release

1. Merge your approved branch into master.
2. Create a new release in GitHub.

   • Click on "Releases" and then "Draft a new release"

   • Set the tag version to a new tag, using Semantic Versioning as a guideline.

   • Set the target as master.

   • Set the Release title to the tag you created, vX.Y.Z

   • Use the description section to describe why you're releasing and what changes you've made. You should include links to merged PRs

   • Consider using the following headers in the description of your release:

     • BREAKING CHANGES: Use this for any changes that aren't backwards compatible. Include details on how to handle these changes.
     • FEATURES: Use this for any large new features added,
     • ENHANCEMENTS: Use this for smaller new features added
     • BUG FIXES: Use this for any bugs that were fixed.
     • NOTES: Use this section if you need to include any additional notes on things like upgrading, upcoming deprecations, or any other information you might want to highlight.

     Markdown example:

     ENHANCEMENTS
     * Add description of new small feature (#3)[link-to-pull-request]
     
     BUG FIXES
     * Fix description of a bug (#2)[link-to-pull-request]
     * Fix description of another bug (#1)[link-to-pull-request]

   • Don't attach any binaries. The zip and tar.gz assets are automatically created and attached after you publish your release.

   • Click "Publish release" to save and publish your release.