» Depending on 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.
Note: a notable exception to this is providers importing other providers in their test files. A better solution for that use case is in the works, but at the moment importing the providers is the best available solution.
» 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
» 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.