Document Relationships Between Terraform Commands, Protocol RPCs, and Framework Functionality

[bflad]

Module version

v1.0.0

Use-cases

The current website documentation mainly serves as a reference for framework functionality, but only off-handedly mentions the functionality's relationship with practitioner usage. For example, it may be confusing to provider developers that provider configuration does not happen before configuration validation due to how Terraform is designed.

A quick reference for what we mean can be found with the below ordered tables --

terraform validate

Protocol RPCs	Framework Functionality
GetProviderSchema	datasource.DataSource, provider.Provider, and resource.Resource interface Schema method
ValidateDataSourceConfig / ValidateProviderConfig / ValidateResourceConfig	datasource.DataSource, provider.Provider, and resource.Resource interface Schema method validators, ConfigValidators method, and ValidateConfig method

terraform plan (with default -refresh=true)

Protocol RPCs	Framework Functionality
GetProviderSchema	datasource.DataSource, provider.Provider, and resource.Resource interface Schema method
ValidateDataSourceConfig / ValidateProviderConfig / ValidateResourceConfig	datasource.DataSource, provider.Provider, and resource.Resource interface Schema method validators, ConfigValidators method, and ValidateConfig method
ConfigureProvider	provider.Provider interface Configure method
ReadDataSource / ReadResource	datasource.DataSource and resource.Resource interface Read method
PlanResourceChange	resource.Resource interface Schema method plan modifiers and ModifyPlan method

terraform apply (with default -refresh=true and without using saved plan file)

Protocol RPCs	Framework Functionality
GetProviderSchema	datasource.DataSource, provider.Provider, and resource.Resource interface Schema method
ValidateDataSourceConfig / ValidateProviderConfig / ValidateResourceConfig	datasource.DataSource, provider.Provider, and resource.Resource interface Schema method validators, ConfigValidators method, and ValidateConfig method
ConfigureProvider	provider.Provider interface Configure method
ReadDataSource / ReadResource	datasource.DataSource and resource.Resource interface Read method
PlanResourceChange	resource.Resource interface Schema method plan modifiers and ModifyPlan method
ApplyResourceChange	resource.Resource interface Create, Update, or Delete method

Attempted Solutions

Discussing these relationships via GitHub Issues and HashiCorp Discuss.

Proposal

Split https://developer.hashicorp.com/terraform/plugin/how-terraform-works#terraform-plugin-protocol into its own page. Document the RPCs there and update the Protocol Buffers definition comments to match. Document roughly when Terraform calls each RPC there.

In the framework documentation for specific functionality, mention and link to associated RPC in the top-level protocol page section for the RPC.

[github-actions]

I'm going to lock this issue because it has been closed for 30 days ⏳. This helps our maintainers find and focus on the active issues.
If you have found a problem that seems similar to this, please open a new issue and complete the issue template so we can capture all the details necessary to investigate further.