Terraform Plugin Go

A low-level Go binding for the Terraform protocol for integrations to be built on top of.
Alternatives To Terraform Plugin Go
Project NameStarsDownloadsRepos Using ThisPackages Using ThisMost Recent CommitTotal ReleasesLatest ReleaseOpen IssuesLicenseLanguage
Terraform Provider Proxmox1,376
2 days ago211mitGo
Terraform provider plugin for proxmox
Terraform Provisioner Ansible526
2 years ago22December 06, 202010apache-2.0Go
Ansible with Terraform 0.14.x
Terraform Plugin Sdk3748303 days ago99October 13, 2022170mpl-2.0Go
Terraform Plugin SDK enables building plugins (providers) to manage any service providers or custom in-house solutions
Terraform Provider Docker363
2 days ago68mpl-2.0Go
Terraform Docker provider
Terraform Provider Rke32212 days ago27October 27, 202245mpl-2.0Go
Terraform provider plugin for deploy kubernetes cluster by RKE(Rancher Kubernetes Engine)
Terraform Provider Gsuite276
2 years ago8May 21, 202128mitGo
A @HashiCorp Terraform provider for managing G Suite resources.
Tfschema25518 months ago23August 12, 20224mitGo
A schema inspector for Terraform providers
Intellij Hcl246
24 days ago103apache-2.0Kotlin
HCL language support for IntelliJ platform based IDEs
Tflint Ruleset Aws22439 days ago63December 11, 20228mpl-2.0Go
TFLint ruleset for terraform-provider-aws
Terraform Provider Vultr169
4 years ago11August 01, 201912mpl-2.0Go
Terraform Vultr Provider
Alternatives To Terraform Plugin Go
Select To Compare

Alternative Project Comparisons



terraform-plugin-go provides low-level Go bindings for the Terraform plugin protocol, for integrations to be built upon. It strives to be a minimal possible abstraction on top of the protocol, only hiding the implementation details of the protocol while leaving its semantics unchanged.


terraform-plugin-go is a Go module versioned using semantic versioning.

The module is currently on a v0 major version, indicating our lack of confidence in the stability of its exported API. Developers depending on it should do so with an explicit understanding that the API may change and shift until we hit v1.0.0, as we learn more about the needs and expectations of developers working with the module.

We are confident in the correctness of the code and it is safe to build on so long as the developer understands that the API may change in backwards incompatible ways and they are expected to be tracking these changes.

Terraform CLI Compatibility

Providers built on terraform-plugin-go will only be usable with Terraform v0.12.0 and later. Developing providers for versions of Terraform below 0.12.0 is unsupported by the Terraform Plugin SDK team.

Go Compatibility

This project follows the support policy of Go as its support policy. The two latest major releases of Go are supported by the project.

Currently, that means Go 1.19 or later must be used when including this project as a dependency.

Getting Started

terraform-plugin-go is targeted towards experienced Terraform developers. Familiarity with the Resource Instance Change Lifecycle is required, and it is the provider developer's responsibility to ensure that Terraform's requirements and invariants for responses are honored.

Provider developers are expected to create a type that implements the tfprotov5.ProviderServer interface. This type should be passed to tfprotov5server.Serve along with the name (like "hashicorp/time").

Resources and data sources can be handled in resource-specific or data source-specific functions by using implementations of the tfprotov5.ResourceServer and tfprotov5.DataSourceServer interfaces, using the provider-level implementations of the interfaces to route to the correct resource or data source level implementations using req.TypeName.

When handling requests, tfprotov5.DynamicValue types should always have their Unmarshal methods called; their properties should not be inspected directly. The tftypes.Value returned from Unmarshal can be inspected to check whether it is known and subsequently converted to a plain Go type using its As method. As will return an error if the Value is not known.


The Terraform Plugin SDK's helper/resource package can be used to test providers written using terraform-plugin-go. While we are working on a testing framework for terraform-plugin-go providers that is independent of the Plugin SDK, this may take some time, so we recommend writing tests in the meantime using the plugin SDK, which will not be a runtime dependency of your provider.

You must supply a factory for your provider server by setting ProtoV5ProviderFactories on each TestCase. For example:

package myprovider

import (


func TestAccDataSourceFoo(t *testing.T) {
	resource.UnitTest(t, resource.TestCase{
		ProtoV5ProviderFactories: map[string]func() (tfprotov5.ProviderServer, error){
			"myprovider": func() (tfprotov5.ProviderServer, error) {
				return Server(), nil
		Steps: []resource.TestStep{
				Config: `"data" "myprovider_foo" "bar" {}`,
				Check: resource.ComposeTestCheckFunc(
					resource.TestMatchResourceAttr("data.myprovider_foo.bar", "current", regexp.MustCompile(`[0-9]+`)),


Provider servers can be instrumented with debugging tooling, such as delve, by using the WithManagedDebug() and WithDebug() ServeOpt. In this mode, Terraform CLI no longer manages the server lifecycle and instead connects to the running provider server via a reattach configuration supplied by the TF_REATTACH_PROVIDERS environment variable. The WithDebug() implementation is meant for advanced use cases which require manually handling the reattach configuration, such as managing providers with terraform-exec, while the WithManagedDebug() implementation is suitable for provider main() functions. For example:

func main() {
	debugFlag := flag.Bool("debug", false, "Start provider in debug mode.")

	opts := []tf6server.ServeOpt{}

	if *debugFlag {
		opts = append(opts, tf6server.WithManagedDebug())

	tf6server.Serve("registry.terraform.io/namespace/example", /* Provider function */, opts...)

Protocol Data

To write raw protocol MessagePack or JSON data to disk, set the TF_LOG_SDK_PROTO_DATA_DIR environment variable. During Terraform execution, this directory will get populated with {TIME}_{RPC}_{MESSAGE}_{FIELD}.{EXTENSION} named files. Tooling such as jq can be used to inspect the JSON data. Tooling such as fq or msgpack2json can be used to inspect the MessagePack data.


Documentation is a work in progress. The GoDoc for packages, types, functions, and methods should have complete information, but we're working to add a section to terraform.io with more information about the module, its common uses, and patterns developers may wish to take advantage of.

Please bear with us as we work to get this information published, and please open issues with requests for the kind of documentation you would find useful.


This module is intentionally limited in its scope. It serves as the foundation for the provider ecosystem, so major breaking changes are incredibly expensive. By limiting the scope of the project, we're limiting the choices it needs to make, making it less likely that breaking changes will be required once we've hit version 1.0.0.

To that end, terraform-plugin-go's scope is limited to providing a common gRPC server interface and an implementation of Terraform's type system. It specifically is not trying to be a framework, nor is it attempting to provide any utility or helper functions that only a subset of provider developers will rely on. Its litmus test for whether something should be included is "will every Terraform provider need this functionality or can this functionality only be added if it's in this module?" All other functionality should be considered out of scope and should live in a separate module.


Please see .github/CONTRIBUTING.md.

Unit Testing

Run go test ./... or make test after any changes.


Ensure the following tooling is installed:

Run golangci-lint run ./... or make lint after any changes.

Protocol Updates

Ensure the following tooling is installed:

  • protoc: Protocol Buffers compiler.
  • protoc-gen-go: Go plugin for Protocol Buffers compiler. e.g. go install google.golang.org/protobuf/cmd/protoc-gen-go
  • protoc-gen-go-grpc: Go gRPC plugin for Protocol Buffers compiler. e.g. go install google.golang.org/grpc/cmd/protoc-gen-go-grpc

The Protocol Buffers definitions can be found in tfprotov5/internal/tfplugin5 and tfprotov6/internal/tfplugin6.

Run make protoc to recompile the Protocol Buffers files after any changes.


This module is licensed under the Mozilla Public License v2.0.

Popular Terraform Projects
Popular Plugin Projects
Popular Configuration Management Categories

Get A Weekly Email With Trending Projects For These Categories
No Spam. Unsubscribe easily at any time.