terraform-plugin-go

terraform-plugin-go provides low-level Go bindings for the Terraformplugin protocol, for integrations to be built upon. It strives to be aminimal possible abstraction on top of the protocol, only hiding theimplementation details of the protocol while leaving its semanticsunchanged.

Status

terraform-plugin-go is aGo moduleversioned usingsemantic versioning.

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

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

Terraform CLI Compatibility

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

Go Compatibility

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

Currently, that means Go1.24 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 theResource Instance ChangeLifecycleis required, and it is the provider developer's responsibility to ensure thatTerraform's requirements and invariants for responses are honored.

Provider developers are expected to create a type that implements thetfprotov5.ProviderServerinterface. This type should be passed totfprotov5server.Servealong with the name (like"hashicorp/time").

Resources and data sources can be handled in resource-specific or datasource-specific functions by using implementations of thetfprotov5.ResourceServerandtfprotov5.DataSourceServerinterfaces, using the provider-level implementations of the interfaces to routeto the correct resource or data source level implementations usingreq.TypeName.

When handling requests,tfprotov5.DynamicValuetypes should always have theirUnmarshalmethods called; their properties should not be inspected directly. Thetftypes.Valuereturned fromUnmarshal can be inspected to checkwhether it isknownand subsequently converted to a plain Go type using itsAsmethod.As will return an error if theValue is not known.

Testing

The Terraform Plugin SDK'shelper/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 settingProtoV5ProviderFactories on eachTestCase. For example:

package myproviderimport ("regexp""testing""github.com/hashicorp/terraform-plugin-go/tfprotov5""github.com/hashicorp/terraform-plugin-sdk/v2/helper/resource")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]+`)),),},},})}

Debugging

Provider servers can be instrumented with debugging tooling, such asdelve, by using theWithManagedDebug() andWithDebug()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 theTF_REATTACH_PROVIDERS environment variable. TheWithDebug() implementation is meant for advanced use cases which require manually handling the reattach configuration, such as managing providers withterraform-exec, while theWithManagedDebug() implementation is suitable for providermain() functions. For example:

func main() {debugFlag := flag.Bool("debug", false, "Start provider in debug mode.")flag.Parse()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 theTF_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 asjq can be used to inspect the JSON data. Tooling such asfq ormsgpack2json can be used to inspect the MessagePack data.

Documentation

Documentation is a work in progress. The GoDoc for packages, types, functions,and methods should have complete information, but we're working to add asection toterraform.io with more information aboutthe module, its common uses, and patterns developers may wish to take advantageof.

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

Scope

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

To that end, terraform-plugin-go's scope is limited to providing a common gRPCserver interface and an implementation of Terraform's type system. Itspecifically is not trying to be a framework, nor is it attempting to provideany utility or helper functions that only a subset of provider developers willrely on. Its litmus test for whether something should be included is "willevery Terraform provider need this functionality or can this functionality onlybe added if it's in this module?" All other functionality should be consideredout of scope and should live in a separate module.

Contributing

Please see.github/CONTRIBUTING.md.

Unit Testing

Rungo test ./... ormake test after any changes.

Linting

Ensure the following tooling is installed:

• `golangci-lint: Aggregate Go linting tool.

Rungolangci-lint run ./... ormake lint after any changes.

Protocol Updates

Ensure the following tooling is installed:

• protoc: Protocol Buffers compiler. This isn't Go specific tooling, so follow thisinstallation guide
  • The Terraform Plugin Protocol uses well-known types (Timestamp), so be sure to copy theinclude directory to a folder included in yourPATH (for example, on MacOS,/usr/local/include).
• protoc-gen-go: Go plugin for Protocol Buffers compiler. Install by runningmake tools
• protoc-gen-go-grpc: Go gRPC plugin for Protocol Buffers compiler. Install by runningmake tools

The Protocol Buffers definitions can be found intfprotov5/internal/tfplugin5 andtfprotov6/internal/tfplugin6.

Runmake protoc to recompile the Protocol Buffers files after any changes.

License

This module is licensed under theMozilla Public License v2.0.