Docs: Diagram when various methods get called and under what conditions

[thiskevinwang]

👋 I'm currently working through my very first terraform provider, and one conceptual thing that I'm having a huge difficult with is knowing/understanding when various methods — ie. resource.Create|Read|Update|Delete — get called, and under what conditions — ie. fresh terraform apply, terraform plan with state populated, etc... there are a good amount of permutations 😅.

The diagrams at https://developer.hashicorp.com/terraform/plugin/framework/internals/rpcs#read-rpcs ...

• https://github.com/hashicorp/terraform-plugin-framework/blob/d3400c5e52f7e5577bf4122dbceaa3084f91da55/website/docs/plugin/framework/internals/rpcs.mdx#L2

... are the closest thing that satisfies this learning need, but I think I still have to read between the lines. A "lifecycle" overview page of sorts would be a very nice addition to the docs. (Also acknowledging that the specific "lifecycle" terminology has some SEO clash implications with the core lifecycle block.

[austinvalle]

Hey there @thiskevinwang 👋🏻 ,

Drive-by note:

I don't believe it satisfies your request fully, but Terraform core has a document that describes the lifecycle of a managed resource that you may find interesting: https://github.com/hashicorp/terraform/blob/main/docs/resource-instance-change-lifecycle.md. This document is written from Terraform core's perspective and references RPCs as it's the abstraction between core and provider SDKs like terraform-plugin-framework and terraform-plugin-sdk/v2. It describes Terraform's data consistency model and how certain values are populated from prior state, proposed state, etc.

I think a similarly structured lifecycle document from the perspective of a Provider (probably Plugin Framework specific) could be useful for building a mental model of "how terraform works". That could be expanding on the existing RPC documentation or potentially something new.

[thiskevinwang]

Woah, thanks @austinvalle! Yea ditto to what you said:

I think a similarly structured lifecycle document from the perspective of a Provider (probably Plugin Framework specific) could be useful for building a mental model of "how terraform works". That could be expanding on the existing RPC documentation or potentially something new.

a more straight-to-the-point version of this diagram 👇, something that is more closely coupled with the code of a provider being developed, would be awesome!

[mmodenesi]

Me too, I need this.

I'm following the providers plugin framework tutorial series (very nice, btw) very carefully, not just copy pasting code, but using it as a reference for my own toy coffees-like service, and I find this bit the most difficult to grasp.

When is tf going to call Update? Why the Update method logic is not about comparing previous state with configuration to see if we need to make PUT requests? Why Read is called during plan, but remote changes are not taken into account? Etc.

Maybe the questions themselves are wrong ("tf won't ever do PUTs! it shall destroy and create"), or show a lack of understanding, and it's not my intention to get answers here, just saying that this would be a very important thing for me too.