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

bendbennett · 2023-01-11T14:30:24Z

Closes: #587
Closes: #640
Closes: #641

The documentation added in this PR contains links which reference changes in Adding Terraform Plugin Protocol top-level section (#241), which should be merged first to avoid broken links in the Framework documentation.

…form commands, RPCs and framework functionality (#587)

bflad · 2023-01-12T19:22:27Z

website/docs/plugin/framework/rpcs.mdx

+
+### Overview
+
+![diagram: GetProviderSchema RPC Overview](/img/get-provider-schema-overview.png)


Can we have HTML comments (or some other documentation added) for how to update these diagrams?

bflad · 2023-01-12T19:38:22Z

website/data/plugin-framework-nav-data.json

+  {
+    "title": "Protocol RPCs",
+    "path": "rpcs"
+  },


Just to raise a slight concern: I'm a little worried that this page is a little too detailed in its current form to be the first potential page of the navigation. The information is real nice (e.g. relating Terraform commands to how they interact with provider code), but I think it might completely overwhelm newer developers with a lot of implementation bits that are not fully necessary for them to successfully develop a provider. I'm not sure I have the best constructive feedback yet on how to address that potential concern though. 🙁

One thing is that we currently have pages for each of the provider implementation details, such as Providers > Validating Configuration. Maybe some of this content could exist towards the bottom of those for advanced readers so its a little more self-contained depending on what a developer is wanting to do. Otherwise, I think we should consider how to link those pages back to this information in some form.

I don't think doing the above would fully alleviate the need for some of the higher level information of this page, but it might help quell the information overload issue by colocating the nitty-gritty RPC details as an "implementation details" section for each of the other pages that has a call out that this information is provided only for developers wanting a more technical deep dive.

Might be best if we discuss how we want to proceed here. I'm more than happy to add information and/or links wherever you think would best serve the reader.

Have refactored following discussion to include a new Internals section in the documentation and link to the RPCs and Framework Functionality page from other pages in the docs.

…and linking RPCs from individual pages (#587)

…n are generated (#587)

…o be removed from the provider schema and transferred to ConfigureFunc or ConfigureContextFunc when using muxing with an SDK provider (#587)

austinvalle

Great work! 👍🏻

bflad

A few minor things, otherwise looks good to me 🚀

bflad · 2023-01-30T18:53:45Z

website/docs/plugin/framework/data-sources/configure.mdx

@@ -51,6 +53,8 @@ func (p *ExampleCloudProvider) Configure(ctx context.Context, req provider.Confi

 Implement the [`datasource.DataSourceWithConfigure` interface](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework/datasource#DataSourceWithConfigure) which receives the provider configured data from the [`Provider` interface `Configure` method](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework/provider#Provider.Configure) and saves it into the [`datasource.DataSource` interface](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework/datasource#DataSource) implementation.

+The [`datasource.DataSourceWithConfigure` interface `Configure` method](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework/datasource#DataSourceWithConfigure.Configure) is called during execution of the [`terraform validate`](/cli/commands/validate), [`terraform plan`](/cli/commands/plan) and [`terraform apply`](/cli/commands/apply) commands when the [`ValidateDataResourceConfig`](/plugin/framework/internals/rpcs#validatedataresourceconfig-rpc) RPC is sent. Additionally, the [`datasource.DataSourceWithConfigure` interface `Configure` method](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework/datasource#DataSourceWithConfigure.Configure) is called during execution of the [`terraform plan`](/cli/commands/plan) and [`terraform apply`](/cli/commands/apply) commands when the [`ReadDataSource`](/plugin/framework/internals/rpcs#readdatasource-rpc) RPC is sent.


I think if we are going to call out this level of detail, then we should clarify that Terraform calling the ValidateDataResourceConfig RPC would not call the ConfigureProvider RPC first, so implementations need to account for that situation. Configuration validation should be "offline" in Terraform.

bflad · 2023-01-30T18:54:43Z

website/docs/plugin/framework/data-sources/timeouts.mdx

-            "timeouts": timeouts.Attributes(ctx, timeouts.Opts{
-                Read: true,
-            }),
+			"timeouts": timeouts.Attributes(ctx),


Nit: Tabs vs spaces

bflad · 2023-01-30T18:59:52Z

website/docs/plugin/framework/internals/rpcs.mdx

+
+### Summary
+
+![diagram: GetProviderSchema RPC Overview](/img/get-provider-schema-overview.png)


Should we include code comments for these to the website/img README?

bflad · 2023-01-30T19:00:10Z

website/docs/plugin/framework/migrating/data-sources/timeouts.mdx

-            "timeouts": timeouts.Attributes(ctx, timeouts.Opts{
-                Read: true,
-            }),
+			"timeouts": timeouts.Attributes(ctx),


Nit: Tabs vs spaces

website/docs/plugin/framework/data-sources/timeouts.mdx

bflad · 2023-01-30T19:03:40Z

website/docs/plugin/framework/migrating/providers/index.mdx

@@ -63,6 +63,28 @@ configuration. Use muxing when you want to release a version of your provider wi
 sources migrated to the Framework. You may want to do this if your provider manages a large number of resources and
 data sources.

+
+~> **Important**: If you are using muxing and your SDK provider schema is using


Doesn't have to be changed now, but FYI about new callout syntax: https://github.com/hashicorp/terraform-providers-devex-internal/issues/124

Will come back to this one. Using <Highlight>....</Highlight> resulted in backtick highlighting being ignored and output literally.

website/docs/plugin/framework/migrating/resources/timeouts.mdx

bflad · 2023-01-30T19:09:31Z

website/docs/plugin/framework/resources/configure.mdx

@@ -51,6 +53,8 @@ func (p *ExampleCloudProvider) Configure(ctx context.Context, req provider.Confi

 Implement the [`resource.ResourceWithConfigure` interface](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework/resource#ResourceWithConfigure) which receives the provider configured data from the [`Provider` interface `Configure` method](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework/provider#Provider.Configure) and saves it into the [`resource.Resource` interface](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework/resource#Resource) implementation.

+The [`resource.ResourceWithConfigure` interface `Configure` method](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework/resource#ResourceWithConfigure.Configure) is called during execution of the [`terraform validate`](/cli/commands/validate), [`terraform plan`](/cli/commands/plan) and [`terraform apply`](/cli/commands/apply) commands when the [`ValidateResourceConfig`](/plugin/framework/internals/rpcs#validateresourceconfig-rpc) RPC is sent. Additionally, the [`resource.ResourceWithConfigure` interface `Configure` method](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework/resource#ResourceWithConfigure.Configure) is called during execution of the [`terraform plan`](/cli/commands/plan) and [`terraform apply`](/cli/commands/apply) commands when the [`ReadResource`](/plugin/framework/internals/rpcs#readresource-rpc) RPC is sent.


Similarly --

I think if we are going to call out this level of detail, then we should clarify that Terraform calling the ValidateDataResourceConfig RPC would not call the ConfigureProvider RPC first, so implementations need to account for that situation. Configuration validation should be "offline" in Terraform.

website/docs/plugin/framework/resources/timeouts.mdx

Co-authored-by: Brian Flad <[email protected]>

…#587)

… .png files (#587)

github-actions · 2023-03-03T02:49:19Z

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

Adding RPCs top-level page to describe the relationship between Terra…

4cac864

…form commands, RPCs and framework functionality (#587)

bendbennett added the documentation Improvements or additions to documentation label Jan 11, 2023

bendbennett added this to the v1.1.0 milestone Jan 11, 2023

Updating formatting and links (#587)

dd69b8d

bendbennett marked this pull request as ready for review January 11, 2023 16:07

bendbennett requested a review from a team as a code owner January 11, 2023 16:07

bflad reviewed Jan 12, 2023

View reviewed changes

bflad modified the milestones: v1.1.0, v1.2.0 Jan 13, 2023

bendbennett added 7 commits January 30, 2023 09:29

Moving RPCs and Framework Functionality into a new internals section …

5d64d15

…and linking RPCs from individual pages (#587)

Fixing links (#587)

3856dfa

Adding README to document how the images used within the documentatio…

9b232fd

…n are generated (#587)

Adding documentation to highlight that Default and DefaultFunc need t…

2b923a0

…o be removed from the provider schema and transferred to ConfigureFunc or ConfigureContextFunc when using muxing with an SDK provider (#587)

Fixing links (#587)

56efbdb

Updating timeouts examples (#587)

772a2cd

Merge branch 'main' into bendbennett/issues-587

dfae414

bendbennett requested a review from bflad January 30, 2023 11:24

austinvalle reviewed Jan 30, 2023

View reviewed changes

bflad approved these changes Jan 30, 2023

View reviewed changes

bendbennett and others added 5 commits January 31, 2023 09:44

Merge branch 'main' into bendbennett/issues-587

820137a

Apply suggestions from code review

e9a28e9

Co-authored-by: Brian Flad <[email protected]>

Add note about when Configure is called on data sources and resources (…

8121780

…#587)

Replacing tabs with spaces (#587)

d77a987

Adding HTML comments to link to README for information on creation of…

7877aff

… .png files (#587)

bendbennett merged commit 007a68b into main Jan 31, 2023

bendbennett deleted the bendbennett/issues-587 branch January 31, 2023 17:45

bendbennett mentioned this pull request Feb 27, 2023

Consider having a waiting interface to satisfy to enable consistant waiting in most resources #665

Open

github-actions bot locked as resolved and limited conversation to collaborators Mar 3, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

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

bendbennett commented Jan 11, 2023 •

edited

Loading

bflad Jan 12, 2023

bflad Jan 12, 2023

bendbennett Jan 17, 2023

bendbennett Jan 30, 2023

austinvalle left a comment

bflad left a comment

bflad Jan 30, 2023

bflad Jan 30, 2023

bflad Jan 30, 2023

bflad Jan 30, 2023

bflad Jan 30, 2023

bendbennett Jan 31, 2023 •

edited

Loading

bflad Jan 30, 2023

github-actions bot commented Mar 3, 2023


		### Overview

		![diagram: GetProviderSchema RPC Overview](/img/get-provider-schema-overview.png)

		@@ -51,6 +53,8 @@ func (p *ExampleCloudProvider) Configure(ctx context.Context, req provider.Confi

		Implement the [`datasource.DataSourceWithConfigure` interface](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework/datasource#DataSourceWithConfigure) which receives the provider configured data from the [`Provider` interface `Configure` method](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework/provider#Provider.Configure) and saves it into the [`datasource.DataSource` interface](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework/datasource#DataSource) implementation.

		The [`datasource.DataSourceWithConfigure` interface `Configure` method](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework/datasource#DataSourceWithConfigure.Configure) is called during execution of the [`terraform validate`](/cli/commands/validate), [`terraform plan`](/cli/commands/plan) and [`terraform apply`](/cli/commands/apply) commands when the [`ValidateDataResourceConfig`](/plugin/framework/internals/rpcs#validatedataresourceconfig-rpc) RPC is sent. Additionally, the [`datasource.DataSourceWithConfigure` interface `Configure` method](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework/datasource#DataSourceWithConfigure.Configure) is called during execution of the [`terraform plan`](/cli/commands/plan) and [`terraform apply`](/cli/commands/apply) commands when the [`ReadDataSource`](/plugin/framework/internals/rpcs#readdatasource-rpc) RPC is sent.


		### Summary

		![diagram: GetProviderSchema RPC Overview](/img/get-provider-schema-overview.png)

		@@ -51,6 +53,8 @@ func (p *ExampleCloudProvider) Configure(ctx context.Context, req provider.Confi

		Implement the [`resource.ResourceWithConfigure` interface](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework/resource#ResourceWithConfigure) which receives the provider configured data from the [`Provider` interface `Configure` method](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework/provider#Provider.Configure) and saves it into the [`resource.Resource` interface](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework/resource#Resource) implementation.

		The [`resource.ResourceWithConfigure` interface `Configure` method](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework/resource#ResourceWithConfigure.Configure) is called during execution of the [`terraform validate`](/cli/commands/validate), [`terraform plan`](/cli/commands/plan) and [`terraform apply`](/cli/commands/apply) commands when the [`ValidateResourceConfig`](/plugin/framework/internals/rpcs#validateresourceconfig-rpc) RPC is sent. Additionally, the [`resource.ResourceWithConfigure` interface `Configure` method](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework/resource#ResourceWithConfigure.Configure) is called during execution of the [`terraform plan`](/cli/commands/plan) and [`terraform apply`](/cli/commands/apply) commands when the [`ReadResource`](/plugin/framework/internals/rpcs#readresource-rpc) RPC is sent.

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

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

Conversation

bendbennett commented Jan 11, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

austinvalle left a comment

Choose a reason for hiding this comment

bflad left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bendbennett Jan 31, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

github-actions bot commented Mar 3, 2023

bendbennett commented Jan 11, 2023 •

edited

Loading

bendbennett Jan 31, 2023 •

edited

Loading