RPCs and Framework Functionality

The correlation between the Terraform command, the RPCs that are issued and the Terraform plugin framework methods that are called is as follows:

terraform validate

terraform plan

terraform apply

GetProviderSchema RPC

Summary

When terraform validate | plan | apply are executed Terraform core issues the GetProviderSchema RPC. The RPC flows through the Terraform plugin framework and ultimately calls the Schema function on the provider and on each of the resources and data sources that the provider defines.

Detail

Within the Terraform plugin framework, terraform-plugin-go is used to expose gRPC endpoints defined by the Terraform plugin protocol. These endpoints implement the tfplugin6.ProviderServer interface for version 6 of the Terraform plugin protocol. The terraform-plugin-go module also defines a tfprotov6.ProviderServer interface which is implemented by the terraform-plugin-framework module, and includes the GetProviderSchema function.

The terraform-plugin-framework module implements the tfprotov6.ProviderServer interface GetProviderSchema function from the terraform-plugin-go module in proto6server.GetProviderSchema. The proto6server.GetProviderSchema function calls fwserver.GetProviderSchema which then calls fwserver.ProviderSchema, fwserver.ResourceSchemas and fwserver.DataSourceSchemas functions. The terraform-plugin-framework module defines provider.Provider, resource.Resource and datasource.DataSource interfaces for providers, resources and data sources, respectively. Each of these interfaces include a Schema function which is implemented by the Terraform provider code written by the provider developer.

In summary, the schemas for the provider and each of the resources and data sources are defined by the provider developer through implementation of the Schema function defined on the provider.Provider, resource.Resource and datasource.DataSource interfaces, respectively. For the GetProviderSchema RPC, the implementation of the Schema function in the provider.Provider, resource.Resource and datasource.DataSource interfaces represents the "touch-point" for where the RPC sent from Terraform core interacts with the code written by the provider developer.

ValidateConfig RPCs

Summary

When terraform validate | plan | apply are executed if the Terraform configuration contains configuration for the provider then Terraform core issues the ValidateProviderConfig RPC. Additionally, the ValidateResourceConfig and ValidateDataResourceConfig RPCs are issued for each of the resources and data sources that appear in the Terraform configuration. There is a 1:1 match between the schema returned from the GetProviderSchema RPC and the Validate<Provider|Resource|DataResource>Config RPCs.

The Validate<Provider|Resource|DataResource>Config RPCs flow through the Terraform plugin framework and ultimately call the Validate<Provider|Resource|DataSource> function on each of the ConfigValidators, the ValidateConfig function on the provider, resource or data source, and each of the Validate<type> functions defined on each of the attributes and blocks within the provider, resource or data source schema.

The ValidateResourceConfig and ValidateDataResourceConfig RPCs additionally call resource.Configure and datasource.Configure, respectively.

Detail

ValidateProviderConfig RPC

ValidateResourceConfig RPC

ValidateDataResourceConfig RPC

Within the Terraform plugin framework, terraform-plugin-go is used to expose gRPC endpoints defined by the Terraform plugin protocol. These endpoints implement the tfplugin6.ProviderServer interface for version 6 of the Terraform plugin protocol. The terraform-plugin-go module also defines tfprotov6.<Provider|Resource|DataSource>Server interfaces which are implemented within the terraform-plugin-framework module.

The terraform-plugin-framework module contains proto6server.Validate<Provider|Resource|DataResource>Config functions which are implementations of the tfprotov6.<Provider|Resource|DataSource>Server interface Validate<Provider|Resource|DataResource>Config functions, respectively. Each of these functions then call fwserver.Validate<Provider|Resource|DataSource>Config functions, respectively.

If the provider, resource or data source implements the <provider|resource|datasource>.<Provider|Resource|DataSource>WithConfigValidators interface defined in the terraform-plugin-framework module, the <provider|resource|datasource>.ConfigValidators function is called to retrieve a slice of <provider|resource|datasource>.ConfigValidator, and then <provider|resource|datasource>.Validate<Provider|Resource|DataSource> is called on each element in the slice sequentially.

If the provider, resource or data source implements the <provider|resource|datasource>.<Provider|Resource|DataSource>WithValidateConfig interface, the <provider|resource|datasource>.ValidateConfig function is called.

The fwserver.SchemaValidate function is then called which iterates over each of the attributes and blocks defined within the provider, resource or data source schema and calls the validator.Validate<type> for each of the validators defined on the attribute or block.

In summary:

• The <provider|resource|datasource>.ConfigValidators and <provider|resource|datasource>.Validate<Provider|Resource|DataSource> functions are optionally defined by the provider developer through implementation of the <provider|resource|datasource>.<Provider|Resource|DataSource>WithConfigValidators interfaces.
• The <provider|resource|datasource>.ValidateConfig functions are optionally defined by the provider developer through implementation of the <provider|resource|datasource>.<Provider|Resource|DataSource>WithValidateConfig interfaces.
• The attribute and block validators are optionally specified by the provider developer by adding a type-specific slice of validators to the attribute or block (e.g., []validator.String{...} on a schema.StringAttribute).

ConfigureProvider RPC

Summary

When terraform plan | apply are executed Terraform core issues the ConfigureProvider RPC.

The ConfigureProvider RPC flows through the Terraform plugin framework and ultimately calls the Configure function on the provider.

Detail

Within the Terraform plugin framework, terraform-plugin-go is used to expose gRPC endpoints defined by the Terraform plugin protocol. These endpoints implement the tfplugin6.ProviderServer interface for version 6 of the Terraform plugin protocol. The terraform-plugin-go module also defines the tfprotov6.ProviderServer interface which is implemented within the terraform-plugin-framework module.

The terraform-plugin-framework module contains a proto6server.ConfigureProvider function which is an implementation of the tfprotov6.ProviderServer interface ConfigureProvider function. The proto6server.ConfigureProvider function calls the fwserver.ConfigureProvider function. The terraform-plugin-framework defines the provider.Provider interface which contains a Configure function. The Configure function is implemented by the provider developer, and this function is called by the fwserver.ConfigureProvider function.

In summary, the provider.Provider interface defines a Configure function which must be defined by the provider developer.

Read RPCs

Summary

When terraform plan | apply are executed Terraform core issues the ReadResource and ReadDataSource RPCs. Note that the ReadResource RPC is only issued when a resource already exists in state.

The ReadResource and ReadDataSource RPCs flow through the Terraform plugin framework and ultimately call the Read function on the resource and data source, respectively.

Detail

ReadResource RPC

ReadDataSource RPC

Within the Terraform plugin framework, terraform-plugin-go is used to expose gRPC endpoints defined by the Terraform plugin protocol. These endpoints implement the tfplugin6.ProviderServer interface for version 6 of the Terraform plugin protocol. The terraform-plugin-go module also defines the tfprotov6.ProviderServer interface which encompasses the tfprotov6.ResourceServer and tfprotov6.DataSourceServer interfaces. The tfprotov6.ProviderServer interface is implemented within the terraform-plugin-framework module.

The terraform-plugin-framework module contains a proto6server.ReadResource function which is an implementation of the tfprotov6.ResourceServer interface ReadResource function. The proto6server.ReadResource function calls the fwserver.ReadResource function. The terraform-plugin-framework defines the resource.ResourceWithConfigure interface which contains a Configure function. If the resource implements the resource.ResourceWithConfigure interface then the Configure function that has been implemented by the provider developer is called. The terraform-plugin-framework defines the resource.Resource interface which contains a Read function which is called by the fwserver.ReadResource function.

The terraform-plugin-framework module contains a proto6server.ReadDataSource function which is an implementation of the tfprotov6.DataSourceServer interface ReadDataSource function. The proto6server.ReadDataSource function calls the fwserver.ReadDataSource function. The terraform-plugin-framework defines the datasource.DataSourceWithConfigure interface which contains a Configure function. If the data source implements the datasource.DataSourceWithConfigure interface then the Configure function that has been implemented by the provider developer is called. The terraform-plugin-framework defines the datasource.DataSource interface which contains a Read function which is called by the fwserver.ReadDataSource function.

In summary, the resource.Resource interface defines a Read function which is called by the ReadResource RPC and the datasource.DataSource interface defines a Read function which is called by the ReadDataSource RPC. All resources and data sources must have provider developer defined Read functions.

PlanResourceChange RPC

Summary

When terraform plan | apply are executed Terraform core issues the PlanResourceChange RPC. Note that the PlanResourceChange RPC is only issued when a resource exists in configuration and/or a resource already exists in state.

The PlanResourceChange RPC flows through the Terraform plugin framework and ultimately calls each of the PlanModify<type> functions on each of the attributes and blocks within the resource schema and ModifyPlan on the resource if the resource.ResourceWithModifyPlan interface has been implemented.

The PlanResourceChange RPC also calls resource.Configure if the resource.ResourceWithConfigure interface has been implemented.

Detail

Within the Terraform plugin framework, terraform-plugin-go is used to expose gRPC endpoints defined by the Terraform plugin protocol. These endpoints implement the tfplugin6.ProviderServer interface for version 6 of the Terraform plugin protocol. The terraform-plugin-go module also defines the tfprotov6.ResourceServer interface which is encompassed by the tfplugin6.ProviderServer interface.

The terraform-plugin-framework module contains the proto6server.PlanResourceChange function which is an implementation of the tfprotov6.ResourceServer interface PlanResourceChange function. The PlanResourceChange function calls the fwserver.PlanResourceChange function.

If the resource implements the resource.ResourceWithConfigure interface, then the resource.Configure function defined by the provider developer is called.

All attributes that are null in the configuration are then marked as unknown in the plan so that a provider has the opportunity to update them. The fwserver.SchemaModifyPlan function is then called which iterates over each of the attributes and blocks defined within the resource schema and calls planmodifier.PlanModify<type> for each of the plan modifiers defined on the attribute or block.

If the resource implements the resource.ResourceWithModifyPlan interface then the provider developer defined resource.ModifyPlan function is called.

In summary, resource.Configure is called on the resource if it implements the resource.ResourceWithConfigure interface. The PlanModify<type> functions on all the plan modifiers defined on each of the attributes and blocks within the resource schema are executed. The resource.ModifyPlan function is called on the resource if it implements the resource.ResourceWithModifyPlan interface.

ApplyResourceChange RPC

Summary

When terraform apply is executed Terraform core issues the ApplyResourceChange RPC. Note that the ApplyResourceChange RPC is only issued when a resource exists in configuration and/or a resource already exists in state.

The ApplyResourceChange RPC flows through the Terraform plugin framework and ultimately calls either resource.Create, resource.Update or resource.Delete on the resource depending upon the contents of the state and the plan.

The ApplyResourceChange RPC also calls resource.Configure method if the resource.ResourceWithConfigure interface has been implemented.

Detail

Within the Terraform plugin framework, terraform-plugin-go is used to expose gRPC endpoints defined by the Terraform plugin protocol. These endpoints implement the tfplugin6.ProviderServer interface for version 6 of the Terraform plugin protocol. The terraform-plugin-go module also defines the tfprotov6.ResourceServer interface which is encompassed by the tfplugin6.ProviderServer interface.

The terraform-plugin-framework module contains the proto6server.ApplyResourceChange function which is an implementation of the tfprotov6.ResourceServer interface ApplyResourceChange function. The ApplyResourceChange function calls the fwserver.ApplyResourceChange function.

If the resource implements the resource.ResourceWithConfigure interface, then the resource.Configure function defined by the provider developer is called.

The resource.Resource interface defined within terraform-plugin-framework contains functions for Create, Update and Delete. The provider developer must implement Create, Update and Delete functions for each resource. Whether the Create, Update or Delete function on the provider is called by the fwserver.ApplyResourceChange function depends on the contents of the state and the plan.

In summary, the ApplyResourcePlan RPC will call resource.Configure on the resource if the resource implements the resource.ResourceWithConfigure interface. One of the provider developer defined Create, Update and Delete functions will be called by the ApplyResourcePlan RPC depending upon the contents of the state and the plan.