From 8c93420270c3593df240ece318e97b24a677b789 Mon Sep 17 00:00:00 2001 From: Brian Flad Date: Thu, 13 Oct 2022 16:29:34 -0400 Subject: [PATCH] docs/plugin-protocol: Add notes about missing configuration in ReadResource and UpgradeResourceState request messages (#31998) This opts to inline document these intentional design decisions in the protocol definition as a catch-all for it not being documented elsewhere. Protocol Buffers files updated via: ```shell make protobuf ``` --- docs/plugin-protocol/tfplugin5.3.proto | 17 +++++++++++++++++ docs/plugin-protocol/tfplugin6.3.proto | 17 +++++++++++++++++ internal/tfplugin5/tfplugin5.pb.go | 17 +++++++++++++++++ internal/tfplugin6/tfplugin6.pb.go | 17 +++++++++++++++++ 4 files changed, 68 insertions(+) diff --git a/docs/plugin-protocol/tfplugin5.3.proto b/docs/plugin-protocol/tfplugin5.3.proto index 5fa53f2339..0f98f04b75 100644 --- a/docs/plugin-protocol/tfplugin5.3.proto +++ b/docs/plugin-protocol/tfplugin5.3.proto @@ -183,6 +183,15 @@ message PrepareProviderConfig { } message UpgradeResourceState { + // Request is the message that is sent to the provider during the + // UpgradeResourceState RPC. + // + // This message intentionally does not include configuration data as any + // configuration-based or configuration-conditional changes should occur + // during the PlanResourceChange RPC. Additionally, the configuration is + // not guaranteed to exist (in the case of resource destruction), be wholly + // known, nor match the given prior state, which could lead to unexpected + // provider behaviors for practitioners. message Request { string type_name = 1; @@ -240,6 +249,14 @@ message Configure { } message ReadResource { + // Request is the message that is sent to the provider during the + // ReadResource RPC. + // + // This message intentionally does not include configuration data as any + // configuration-based or configuration-conditional changes should occur + // during the PlanResourceChange RPC. Additionally, the configuration is + // not guaranteed to be wholly known nor match the given prior state, which + // could lead to unexpected provider behaviors for practitioners. message Request { string type_name = 1; DynamicValue current_state = 2; diff --git a/docs/plugin-protocol/tfplugin6.3.proto b/docs/plugin-protocol/tfplugin6.3.proto index b87effe434..e3fa9d10b1 100644 --- a/docs/plugin-protocol/tfplugin6.3.proto +++ b/docs/plugin-protocol/tfplugin6.3.proto @@ -201,6 +201,15 @@ message ValidateProviderConfig { } message UpgradeResourceState { + // Request is the message that is sent to the provider during the + // UpgradeResourceState RPC. + // + // This message intentionally does not include configuration data as any + // configuration-based or configuration-conditional changes should occur + // during the PlanResourceChange RPC. Additionally, the configuration is + // not guaranteed to exist (in the case of resource destruction), be wholly + // known, nor match the given prior state, which could lead to unexpected + // provider behaviors for practitioners. message Request { string type_name = 1; @@ -258,6 +267,14 @@ message ConfigureProvider { } message ReadResource { + // Request is the message that is sent to the provider during the + // ReadResource RPC. + // + // This message intentionally does not include configuration data as any + // configuration-based or configuration-conditional changes should occur + // during the PlanResourceChange RPC. Additionally, the configuration is + // not guaranteed to be wholly known nor match the given prior state, which + // could lead to unexpected provider behaviors for practitioners. message Request { string type_name = 1; DynamicValue current_state = 2; diff --git a/internal/tfplugin5/tfplugin5.pb.go b/internal/tfplugin5/tfplugin5.pb.go index 85ab54eab6..92bf7a0a0c 100644 --- a/internal/tfplugin5/tfplugin5.pb.go +++ b/internal/tfplugin5/tfplugin5.pb.go @@ -1800,6 +1800,15 @@ func (x *PrepareProviderConfig_Response) GetDiagnostics() []*Diagnostic { return nil } +// Request is the message that is sent to the provider during the +// UpgradeResourceState RPC. +// +// This message intentionally does not include configuration data as any +// configuration-based or configuration-conditional changes should occur +// during the PlanResourceChange RPC. Additionally, the configuration is +// not guaranteed to exist (in the case of resource destruction), be wholly +// known, nor match the given prior state, which could lead to unexpected +// provider behaviors for practitioners. type UpgradeResourceState_Request struct { state protoimpl.MessageState sizeCache protoimpl.SizeCache @@ -2236,6 +2245,14 @@ func (x *Configure_Response) GetDiagnostics() []*Diagnostic { return nil } +// Request is the message that is sent to the provider during the +// ReadResource RPC. +// +// This message intentionally does not include configuration data as any +// configuration-based or configuration-conditional changes should occur +// during the PlanResourceChange RPC. Additionally, the configuration is +// not guaranteed to be wholly known nor match the given prior state, which +// could lead to unexpected provider behaviors for practitioners. type ReadResource_Request struct { state protoimpl.MessageState sizeCache protoimpl.SizeCache diff --git a/internal/tfplugin6/tfplugin6.pb.go b/internal/tfplugin6/tfplugin6.pb.go index 6e101cd21b..14322551fc 100644 --- a/internal/tfplugin6/tfplugin6.pb.go +++ b/internal/tfplugin6/tfplugin6.pb.go @@ -1819,6 +1819,15 @@ func (x *ValidateProviderConfig_Response) GetDiagnostics() []*Diagnostic { return nil } +// Request is the message that is sent to the provider during the +// UpgradeResourceState RPC. +// +// This message intentionally does not include configuration data as any +// configuration-based or configuration-conditional changes should occur +// during the PlanResourceChange RPC. Additionally, the configuration is +// not guaranteed to exist (in the case of resource destruction), be wholly +// known, nor match the given prior state, which could lead to unexpected +// provider behaviors for practitioners. type UpgradeResourceState_Request struct { state protoimpl.MessageState sizeCache protoimpl.SizeCache @@ -2255,6 +2264,14 @@ func (x *ConfigureProvider_Response) GetDiagnostics() []*Diagnostic { return nil } +// Request is the message that is sent to the provider during the +// ReadResource RPC. +// +// This message intentionally does not include configuration data as any +// configuration-based or configuration-conditional changes should occur +// during the PlanResourceChange RPC. Additionally, the configuration is +// not guaranteed to be wholly known nor match the given prior state, which +// could lead to unexpected provider behaviors for practitioners. type ReadResource_Request struct { state protoimpl.MessageState sizeCache protoimpl.SizeCache