README

Terraform Plugin SDK

This SDK enables building Terraform plugin which allows Terraform's users to manage existing and popular service providers as well as custom in-house solutions.

Terraform itself is a tool for building, changing, and versioning infrastructure safely and efficiently. You can find more about Terraform on its website and its GitHub repository.

Terraform CLI Compatibility

The v1 major release of the Terraform Plugin SDK supports Terraform 0.11 and later.

It cannot, however, take advantage of all newer features and capabilities in releases of Terraform after 0.11.

Testing using the reattach-based binary test driver, which is opt-in, requires the test runner to be using Terraform 0.12.26 or later. Only test runners, not users, have this requirement.

Go Compatibility

The Terraform Plugin SDK is built in Go, and uses the support policy of Go as its support policy. The two latest major releases of Go are supported by the SDK.

Documentation

See Extending Terraform section on the website.

Scope (Providers VS Core)

Terraform Core
  • acts as gRPC client
  • interacts with the user
  • parses (HCL/JSON) configuration
  • manages state as whole, asks Provider(s) to mutate provider-specific parts of state
  • handles backends & provisioners
  • handles inputs, outputs, modules, and functions
  • discovers Provider(s) and their versions per configuration
  • manages Provider(s) lifecycle (i.e. spins up & tears down provider process)
  • passes relevant parts of parsed (valid JSON/HCL) and interpolated configuration to Provider(s)
  • decides ordering of (Create, Read, Update, Delete) operations on resources and data sources
  • ...
Terraform Provider (via this SDK)
  • acts as gRPC server
  • executes any domain-specific logic based on received parsed configuration
    • (Create, Read, Update, Delete, Import, Validate) a Resource
    • Read a Data Source
  • tests domain-specific logic via provided acceptance test framework
  • provides Core updated state of a resource or data source and/or appropriate feedback in the form of validation or other errors

Migrating to SDK v1 from built-in SDK

Migrating to the standalone SDK v1 is covered on the Plugin SDK section of the website.

Versioning

The Terraform Plugin SDK is a Go module versioned using semantic versioning. See SUPPORT.md for information on our support policies.

Contributing

See .github/CONTRIBUTING.md

License

Mozilla Public License v2.0

Expand ▾ Collapse ▴

Directories

Path Synopsis
Package acctest provides the ability to opt in to the new binary test driver.
Package acctest provides the ability to opt in to the new binary test driver.
helper
acctest
Package acctest contains for Terraform Acceptance Tests
Package acctest contains for Terraform Acceptance Tests
customdiff
Package customdiff provides a set of reusable and composable functions to enable more "declarative" use of the CustomizeDiff mechanism available for resources in package helper/schema.
Package customdiff provides a set of reusable and composable functions to enable more "declarative" use of the CustomizeDiff mechanism available for resources in package helper/schema.
pathorcontents
Helpers for dealing with file paths and their contents
Helpers for dealing with file paths and their contents
schema
schema is a high-level framework for easily writing new providers for Terraform.
schema is a high-level framework for easily writing new providers for Terraform.
The meta package provides a location to set the release version and any other relevant metadata for the SDK.
The meta package provides a location to set the release version and any other relevant metadata for the SDK.
internal
addrs
Package addrs contains types that represent "addresses", which are references to specific objects within a Terraform configuration or state.
Package addrs contains types that represent "addresses", which are references to specific objects within a Terraform configuration or state.
command/format
Package format contains helpers for formatting various Terraform structures for human-readabout output.
Package format contains helpers for formatting various Terraform structures for human-readabout output.
configs
Package configs contains types that represent Terraform configurations and the different elements thereof.
Package configs contains types that represent Terraform configurations and the different elements thereof.
configs/configload
Package configload knows how to install modules into the .terraform/modules directory and to load modules from those installed locations.
Package configload knows how to install modules into the .terraform/modules directory and to load modules from those installed locations.
configs/configschema
Package configschema contains types for describing the expected structure of a configuration block whose shape is not known until runtime.
Package configschema contains types for describing the expected structure of a configuration block whose shape is not known until runtime.
dag
earlyconfig
Package earlyconfig is a specialized alternative to the top-level "configs" package that does only shallow processing of configuration and is therefore able to be much more liberal than the full config loader in what it accepts.
Package earlyconfig is a specialized alternative to the top-level "configs" package that does only shallow processing of configuration and is therefore able to be much more liberal than the full config loader in what it accepts.
helper/experiment
experiment package contains helper functions for tracking experimental features throughout Terraform.
experiment package contains helper functions for tracking experimental features throughout Terraform.
helper/plugin
Package plugin contains types and functions to help Terraform plugins implement the plugin rpc interface.
Package plugin contains types and functions to help Terraform plugins implement the plugin rpc interface.
initwd
Package initwd contains various helper functions used by the "terraform init" command to initialize a working directory.
Package initwd contains various helper functions used by the "terraform init" command to initialize a working directory.
lang
Package lang deals with the runtime aspects of Terraform's configuration language, with concerns such as expression evaluation.
Package lang deals with the runtime aspects of Terraform's configuration language, with concerns such as expression evaluation.
lang/blocktoattr
Package blocktoattr includes some helper functions that can perform preprocessing on a HCL body where a configschema.Block schema is available in order to allow list and set attributes defined in the schema to be optionally written by the user as block syntax.
Package blocktoattr includes some helper functions that can perform preprocessing on a HCL body where a configschema.Block schema is available in order to allow list and set attributes defined in the schema to be optionally written by the user as block syntax.
modsdir
Package modsdir is an internal package containing the model types used to represent the manifest of modules in a local modules cache directory.
Package modsdir is an internal package containing the model types used to represent the manifest of modules in a local modules cache directory.
moduledeps
Package moduledeps contains types that can be used to describe the providers required for all of the modules in a module tree.
Package moduledeps contains types that can be used to describe the providers required for all of the modules in a module tree.
plans
Package plans contains the types that are used to represent Terraform plans.
Package plans contains the types that are used to represent Terraform plans.
plans/internal/planproto
Package planproto is home to the Go stubs generated from the tfplan protobuf schema.
Package planproto is home to the Go stubs generated from the tfplan protobuf schema.
plans/objchange
Package objchange deals with the business logic of taking a prior state value and a config value and producing a proposed new merged value, along with other related rules in this domain.
Package objchange deals with the business logic of taking a prior state value and a config value and producing a proposed new merged value, along with other related rules in this domain.
plans/planfile
Package planfile deals with the file format used to serialize plans to disk and then deserialize them back into memory later.
Package planfile deals with the file format used to serialize plans to disk and then deserialize them back into memory later.
plugin/mock_proto
Package mock_tfplugin5 is a generated GoMock package.
Package mock_tfplugin5 is a generated GoMock package.
providers
Package providers contains the interface and primary types required to implement a Terraform resource provider.
Package providers contains the interface and primary types required to implement a Terraform resource provider.
provisioners
Package provisioners contains the interface and primary types to implement a Terraform resource provisioner.
Package provisioners contains the interface and primary types to implement a Terraform resource provisioner.
registry/regsrc
Package regsrc provides helpers for working with source strings that identify resources within a Terraform registry.
Package regsrc provides helpers for working with source strings that identify resources within a Terraform registry.
states
Package states contains the types that are used to represent Terraform states.
Package states contains the types that are used to represent Terraform states.
states/statefile
Package statefile deals with the file format used to serialize states for persistent storage and then deserialize them into memory again later.
Package statefile deals with the file format used to serialize states for persistent storage and then deserialize them into memory again later.
tfdiags
Package tfdiags is a utility package for representing errors and warnings in a manner that allows us to produce good messages for the user.
Package tfdiags is a utility package for representing errors and warnings in a manner that allows us to produce good messages for the user.
version
The version package provides a location to set the release versions for all packages to consume, without creating import cycles.
The version package provides a location to set the release versions for all packages to consume, without creating import cycles.