Resource pre-planned private data

.changes/v1.15/NEW FEATURES-20251217-113349.yaml

@@ -0,0 +1,5 @@
+kind: NEW FEATURES
+body: Store PlannedPrivate data for providers
+time: 2025-12-17T11:33:49.911997-05:00
+custom:
+    Issue: "37986"

docs/plugin-protocol/tfplugin6.proto

@@ -1,9 +1,9 @@
 // Copyright (c) HashiCorp, Inc.
 // SPDX-License-Identifier: MPL-2.0
 
-// Terraform Plugin RPC protocol version 6.10
+// Terraform Plugin RPC protocol version 6.11
 //
-// This file defines version 6.10 of the RPC protocol. To implement a plugin
+// This file defines version 6.11 of the RPC protocol. To implement a plugin
 // against this protocol, copy this definition into your own codebase and
 // use protoc to generate stubs for your target language.
 //
@@ -310,6 +310,11 @@ message ClientCapabilities {
     // The write_only_attributes_allowed capability signals that the client
     // is able to handle write_only attributes for managed resources.
     bool write_only_attributes_allowed = 2;
+
+    // store_planned_private indicates that the client will store the private data
+    // returned with an initial plan, and send it back to the provider as
+    // PlannedPrivate data in a subsequent plan request.
+    bool store_planned_private = 3;
 }
 
 // Deferred is a message that indicates that change is deferred for a reason.
@@ -641,6 +646,7 @@ message PlanResourceChange {
         DynamicValue provider_meta = 6;
         ClientCapabilities client_capabilities = 7;
         ResourceIdentityData prior_identity = 8;
+        bytes planned_private = 9;
     }
 
     message Response {

internal/providers/provider.go

@@ -298,6 +298,11 @@ type ClientCapabilities struct {
 	// The write_only_attributes_allowed capability signals that the client
 	// is able to handle write_only attributes for managed resources.
 	WriteOnlyAttributesAllowed bool
+
+	// StorePlannedPrivate indicates that the client is will store private data
+	// returned from PlanResourceChange, and return it with the final
+	// PlanResourceChange call.
+	StorePlannedPrivate bool
 }
 
 type ValidateProviderConfigRequest struct {
@@ -547,6 +552,11 @@ type PlanResourceChangeRequest struct {
 	// provider during the last apply.
 	PriorPrivate []byte
 
+	// PlannedPrivate is the private data stored from the the last plan.
+	// PlannedPrivate will only be supplied in the plan immediately preceding an
+	// ApplyResourceChange call.
+	PlannedPrivate []byte
+
 	// ProviderMeta is the configuration for the provider_meta block for the
 	// module and provider this resource belongs to. Its use is defined by
 	// each provider, and it should not be used without coordination with

internal/terraform/context_plan_test.go

@@ -1748,6 +1748,7 @@ func TestContext2Plan_blockNestingGroup(t *testing.T) {
 		ClientCapabilities: providers.ClientCapabilities{
 			DeferralAllowed:            false,
 			WriteOnlyAttributesAllowed: true,
+			StorePlannedPrivate:        true,
 		},
 	}
 	if !cmp.Equal(got, want, valueTrans) {

internal/terraform/eval_context_builtin.go

@@ -637,6 +637,7 @@ func (ctx *BuiltinEvalContext) ClientCapabilities() providers.ClientCapabilities
 	return providers.ClientCapabilities{
 		DeferralAllowed:            ctx.Deferrals().DeferralAllowed(),
 		WriteOnlyAttributesAllowed: true,
+		StorePlannedPrivate:        true,
 	}
 }
 

internal/terraform/node_resource_abstract_instance.go

@@ -832,10 +832,12 @@ func (n *NodeAbstractResourceInstance) plan(
 	if n.preDestroyRefresh {
 		checkRuleSeverity = tfdiags.Warning
 	}
-
+	var plannedPrivate []byte
 	if plannedChange != nil {
 		// If we already planned the action, we stick to that plan
 		createBeforeDestroy = plannedChange.Action == plans.CreateThenDelete
+
+		plannedPrivate = plannedChange.Private
 	}
 
 	// Evaluate the configuration
@@ -985,6 +987,7 @@ func (n *NodeAbstractResourceInstance) plan(
 			ProviderMeta:       metaConfigVal,
 			ClientCapabilities: ctx.ClientCapabilities(),
 			PriorIdentity:      priorIdentity,
+			PlannedPrivate:     plannedPrivate,
 		})
 		// If we don't support deferrals, but the provider reports a deferral and does not
 		// emit any error level diagnostics, we should emit an error.
@@ -1003,7 +1006,7 @@ func (n *NodeAbstractResourceInstance) plan(
 	}
 
 	plannedNewVal := resp.PlannedState
-	plannedPrivate := resp.PlannedPrivate
+	plannedPrivate = resp.PlannedPrivate
 	plannedIdentity := resp.PlannedIdentity
 
 	// These checks are only relevant if the provider is not deferring the