Interacting with Providers

Terraform's providers are a substantial amount of code, and occasionally it makes sense to depend on their functionality. The most straightforward and obvious way to depend on a provider is to depend on the Terraform CLI, but occasionally it makes sense to rely on a provider in a different context.

This guide lays out the supported ways to interface with and depend on Terraform's providers. Unless the provider explicitly states otherwise, no other compatibility guarantees are provided.

Do Not Import Providers as Go Modules

Terraform's providers are written as Go packages, and they mostly use Go modules as their dependency management solution. This makes it tempting to import the provider as a dependency of your Go code, and to call its exposed interface. This is explicitly an unsupported way to interact with providers and provider maintainers make no guarantees around backwards compatibility or the continued functioning of code that does this.

Providers are unable to be imported as Go modules reliably because their versioning scheme is intended to convey information about the Terraform config interface the provider presents. It's unable to capture both the configuration interface and the Go API interface in a useful way, as what is compatible in one may not be compatible in the other. Rather than give the impression that the package should be imported by using the /vX suffix now mandated for versions after 2.0.0, providers have chosen to make their incompatibility with being imported into Go code explicit.

If you find yourself needing to do this, perhaps one of the methods below will work for you, and is explicitly supported and covered under versioning policies. If not, please reach out and open an issue outlining your use case, and we'll work with you to find an appropriate way to interface with Terraform to meet your use case.

Exporting the Schema

Some projects just care about the schema and resources a provider presents. As of Terraform 0.12, the terraform providers schema -json command can be used to export a JSON representation of the schemas for the providers used in a workspace.

Using the RPC Protocol

For projects that actually want to drive the provider, the supported option is to use the gRPC protocol and the RPC calls the protocol supplies. This protocol is the same protocol that drives Terraform's CLI interface, and it is versioned using a protocol version. It changes relatively infrequently.