website: Document managed resource Read and UpgradeState unknown valu…

…e errors Reference: #902 Reference: hashicorp/terraform#34502 Reference: hashicorp/terraform#34503 Unknown values are never valid in resource state and while Terraform nor the framework actually raise these errors right now, one or both will in the near future. This documents the errant implementation detail for developers in the meantime since it otherwise causes confusing Terraform behaviors for practitioners.
hashicorp · Jan 9, 2024 · 70962d7 · 70962d7
1 parent 18af0e8
commit 70962d7
Show file tree

Hide file tree

Showing 2 changed files with 14 additions and 0 deletions.
diff --git a/website/docs/plugin/framework/resources/read.mdx b/website/docs/plugin/framework/resources/read.mdx
@@ -147,6 +147,13 @@ func (r *ThingResource) Read(ctx context.Context, req resource.ReadRequest, resp
 }
 ```
 
+## Caveats
+
+Note these caveats when implementing the `Read` method:
+
+* An error is returned if the response state contains unknown values. Set all attributes to either null or known values in the response.
+* Any response errors will cause Terraform to keep the prior resource state.
+
 ## Recommendations
 
 Note these recommendations when implementing the `Read` method:

diff --git a/website/docs/plugin/framework/resources/state-upgrade.mdx b/website/docs/plugin/framework/resources/state-upgrade.mdx
@@ -285,3 +285,10 @@ func (r *ThingResource) UpgradeState(ctx context.Context) map[int64]resource.Sta
     }
 }
 ```
+
+## Caveats
+
+Note these caveats when implementing the `UpgradeState` method:
+
+* An error is returned if the response state contains unknown values. Set all attributes to either null or known values in the response.
+* Any response errors will cause Terraform to keep the prior resource state.