HashiConf 2024 Now streaming live from Boston! Attend for free
Terraform
Terraform Home

Terraform Plugin Protocol

The Terraform Plugin Protocol is a versioned interface between Terraform CLI and Terraform Plugins.

During discovery, the Terraform Registry uses the protocol version as additional compatibility metadata when deciding which plugin versions Terraform CLI can select. You can configure this metadata in the Terraform Registry manifest file when you create a plugin release.

Major versions of the protocol delineate Terraform CLI and Terraform Plugin compatibility. Minor versions of the protocol are additive. The protocol is implemented in Protocol Buffers and gRPC, with the canonical source for protocol definitions located in the Terraform CLI repository.

Protocol Version 6

Protocol version 6 is compatible with Terraform CLI version 1.0 and later. Protocol version 6 includes all version 5 functionality for providers, plus:

  • Nested Attributes: Define SchemaAttribute with the NestedType field.
    • Enable practitioners to use easier argument syntax instead of block syntax.
    • Configure value sensitivity on individual nested attributes, rather than an entire read-only (Computed only) attribute.

Implementations include:

  • terraform-plugin-framework: A higher-level SDK that makes Terraform provider development easier by abstracting implementation details.
  • terraform-plugin-go tf6server: A lower-level SDK to develop Terraform providers for more advanced use cases.
  • tf5to6server: A package to translate protocol version 5 providers into protocol version 6.
  • tf6muxserver: A package to combine multiple protocol version 6 providers.

Protocol Version 5

Protocol version 5 is compatible with Terraform CLI version 0.12 and later.

Implementations include:

  • terraform-plugin-framework: A higher-level SDK that makes Terraform provider development easier by abstracting implementation details.
  • terraform-plugin-sdk/v2: A higher-level SDK that makes Terraform provider development easier by abstracting implementation details.
  • terraform-plugin-go tf5server: A lower-level SDK to develop Terraform providers for more advanced use cases.
  • tf6to5server: A package to translate protocol version 6 providers into protocol version 5.
  • tf5muxserver: A package to combine multiple protocol version 5 providers.

Protocol RPCs

The Terraform plugin protocol specifies the following RPCs:

Protocol Version 5Protocol Version 6Description
GetSchemaGetProviderSchemaReturns provider schema, provider metaschema, all resource schemas and all data source schemas.
GetMetadataGetMetadataReturns data source, managed resource, and function metadata, such as names.
GetFunctionsGetFunctionsReturns function definitions.
CallFunctionCallFunctionCalled when a practioner configuration contains a provider-defined function.
PrepareProviderConfigValidateProviderConfigValidates the practitioner supplied provider configuration by verifying types conform to the schema and supports value validation diagnostics.
ValidateResourceTypeConfigValidateResourceConfigValidates the practitioner supplied resource configuration by verifying types conform to the schema and supports value validation diagnostics.
ValidateDataSourceConfigValidateDataResourceConfigValidates the practitioner supplied data source configuration by verifying types conform to the schema and supports value validation diagnostics.
UpgradeResourceStateUpgradeResourceStateCalled when a resource has existing state. Primarily useful for when the schema version does not match the current version. The provider is expected to modify the state to upgrade it to the latest schema.
ConfigureConfigureProviderPasses the practitioner supplied provider configuration to the provider.
ReadResourceReadResourceCalled when refreshing a resource's state.
ReadDataSourceReadDataSourceCalled when refreshing a data source's state.
PlanResourceChangePlanResourceChangeCalculates a plan for a resource. A proposed new state is generated, which the provider can modify.
ApplyResourceChangeApplyResourceChangeCalled when a practitioner has approved a planned change. The provider is to apply the changes contained in the plan, and return a resulting state matching the given plan.
ImportResourceStateImportResourceStateCalled when importing a resource into state so that the resource becomes managed.

diagram: Terraform Plugin Protocol 6 RPCs

RPCs and Terraform commands

The following illustrate the RPCs that are sent during execution of the specified Terraform commands.

The RPCs issued are for a provider that is using version 6 of the Terraform plugin protocol when the Terraform configuration contains configuration for the provider, a resource and a data source.

terraform validate

Executing terraform validate results in the following unique RPCs:

diagram: Terraform Plugin Protocol 6 Validate RPCs

The general sequence of RPCs is as follows:

  • GetProviderSchema
  • CallFunction
  • ValidateProviderConfig
  • ValidateResourceConfig
  • ValidateDataResourceConfig

terraform plan

Executing terraform plan results in the following unique RPCs:

diagram: Terraform Plugin Protocol 6 Plan RPCs

The general sequence of RPCs is as follows:

  • GetProviderSchema
  • CallFunction
  • ValidateProviderConfig
  • ValidateResourceConfig
  • ValidateDataResourceConfig
  • ConfigureProvider
  • ReadDataSource
  • PlanResourceChange

terraform apply

Executing terraform apply (with default -refresh=true and -auto-approve) results in the following unique RPCs:

diagram: Terraform Plugin Protocol 6 Plan RPCs

The general sequence of RPCs is as follows:

  • GetProviderSchema
  • CallFunction
  • ValidateProviderConfig
  • ValidateResourceConfig
  • ValidateDataResourceConfig
  • ConfigureProvider
  • UpgradeResourceState
    • only called if resource already exists in state
  • ReadResource
    • only called if resource already exists in state
  • ReadDataSource
  • PlanResourceChange
  • ApplyResourceChange
Edit this page on GitHub