all: Add automatic deferred action support for unknown provider configuration

.changes/unreleased/FEATURES-20240506-152018.yaml

@@ -0,0 +1,6 @@
+kind: FEATURES
+body: 'helper/schema: Added `(Provider).ConfigureProvider` function for configuring
+  providers that support additional features, such as deferred actions.'
+time: 2024-05-06T15:20:18.393505-04:00
+custom:
+  Issue: "1335"

.changes/unreleased/FEATURES-20240506-152135.yaml

@@ -0,0 +1,6 @@
+kind: FEATURES
+body: 'helper/schema: Added `(Resource).ResourceBehavior` to allow additional control
+  over deferred action behavior during plan modification.'
+time: 2024-05-06T15:21:35.304825-04:00
+custom:
+  Issue: "1335"

go.mod

@@ -16,7 +16,7 @@ require (
 	github.com/hashicorp/logutils v1.0.0
 	github.com/hashicorp/terraform-exec v0.20.0
 	github.com/hashicorp/terraform-json v0.21.0
-	github.com/hashicorp/terraform-plugin-go v0.22.2
+	github.com/hashicorp/terraform-plugin-go v0.22.3-0.20240506143625-1296f392daef
 	github.com/hashicorp/terraform-plugin-log v0.9.0
 	github.com/mitchellh/copystructure v1.2.0
 	github.com/mitchellh/go-testing-interface v1.14.1
@@ -55,5 +55,5 @@ require (
 	google.golang.org/appengine v1.6.8 // indirect
 	google.golang.org/genproto/googleapis/rpc v0.0.0-20240227224415-6ceb2ff114de // indirect
 	google.golang.org/grpc v1.63.2 // indirect
-	google.golang.org/protobuf v1.33.0 // indirect
+	google.golang.org/protobuf v1.34.0 // indirect
 )

go.sum

@@ -72,8 +72,10 @@ github.com/hashicorp/terraform-exec v0.20.0 h1:DIZnPsqzPGuUnq6cH8jWcPunBfY+C+M8J
 github.com/hashicorp/terraform-exec v0.20.0/go.mod h1:ckKGkJWbsNqFKV1itgMnE0hY9IYf1HoiekpuN0eWoDw=
 github.com/hashicorp/terraform-json v0.21.0 h1:9NQxbLNqPbEMze+S6+YluEdXgJmhQykRyRNd+zTI05U=
 github.com/hashicorp/terraform-json v0.21.0/go.mod h1:qdeBs11ovMzo5puhrRibdD6d2Dq6TyE/28JiU4tIQxk=
-github.com/hashicorp/terraform-plugin-go v0.22.2 h1:5o8uveu6eZUf5J7xGPV0eY0TPXg3qpmwX9sce03Bxnc=
-github.com/hashicorp/terraform-plugin-go v0.22.2/go.mod h1:drq8Snexp9HsbFZddvyLHN6LuWHHndSQg+gV+FPkcIM=
+github.com/hashicorp/terraform-plugin-go v0.22.3-0.20240503133000-f7070c19a38c h1:TG3MBcQOW3+h7QjtY61HicrSbcyALuJdCF7wgjQIz7w=
+github.com/hashicorp/terraform-plugin-go v0.22.3-0.20240503133000-f7070c19a38c/go.mod h1:1E3Cr9h2vMlahWMbsSEcNrOCxovCZhOOIXjFHbjc/lQ=
+github.com/hashicorp/terraform-plugin-go v0.22.3-0.20240506143625-1296f392daef h1:EaFkrtMi2qVaWkyeGENcbRSEoNiQ78QJtNB/BSzLtMs=
+github.com/hashicorp/terraform-plugin-go v0.22.3-0.20240506143625-1296f392daef/go.mod h1:1E3Cr9h2vMlahWMbsSEcNrOCxovCZhOOIXjFHbjc/lQ=
 github.com/hashicorp/terraform-plugin-log v0.9.0 h1:i7hOA+vdAItN1/7UrfBqBwvYPQ9TFvymaRGZED3FCV0=
 github.com/hashicorp/terraform-plugin-log v0.9.0/go.mod h1:rKL8egZQ/eXSyDqzLUuwUYLVdlYeamldAHSxjUFADow=
 github.com/hashicorp/terraform-registry-address v0.2.3 h1:2TAiKJ1A3MAkZlH1YI/aTVcLZRu7JseiXNRHbOAyoTI=
@@ -198,8 +200,8 @@ google.golang.org/grpc v1.63.2 h1:MUeiw1B2maTVZthpU5xvASfTh3LDbxHd6IJ6QQVU+xM=
 google.golang.org/grpc v1.63.2/go.mod h1:WAX/8DgncnokcFUldAxq7GeB5DXHDbMF+lLvDomNkRA=
 google.golang.org/protobuf v1.26.0-rc.1/go.mod h1:jlhhOSvTdKEhbULTjvd4ARK9grFBp09yW+WbY/TyQbw=
 google.golang.org/protobuf v1.26.0/go.mod h1:9q0QmTI4eRPtz6boOQmLYwt+qCgq0jsYwAQnmE0givc=
-google.golang.org/protobuf v1.33.0 h1:uNO2rsAINq/JlFpSdYEKIZ0uKD/R9cpdv0T+yoGwGmI=
-google.golang.org/protobuf v1.33.0/go.mod h1:c6P6GXX6sHbq/GpV6MGZEdwhWPcYBgnhAHhKbcUYpos=
+google.golang.org/protobuf v1.34.0 h1:Qo/qEd2RZPCf2nKuorzksSknv0d3ERwp1vFG38gSmH4=
+google.golang.org/protobuf v1.34.0/go.mod h1:c6P6GXX6sHbq/GpV6MGZEdwhWPcYBgnhAHhKbcUYpos=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/check.v1 v1.0.0-20180628173108-788fd7840127 h1:qIbj1fsPNlZgppZ+VLlY7N33q108Sa+fhmuc+sWQYwY=
 gopkg.in/check.v1 v1.0.0-20180628173108-788fd7840127/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=

helper/schema/deferred_response.go

@@ -0,0 +1,39 @@
+// Copyright (c) HashiCorp, Inc.
+// SPDX-License-Identifier: MPL-2.0
+
+package schema
+
+// MAINTAINER NOTE: Only PROVIDER_CONFIG_UNKNOWN (enum value 2 in the plugin-protocol) is relevant
+// for SDKv2. Since (DeferredResponse).DeferredReason is mapped directly to the plugin-protocol,
+// the other enum values are intentionally omitted here.
+const (
+	// DeferredReasonUnknown is used to indicate an invalid `DeferredReason`.
+	// Provider developers should not use it.
+	DeferredReasonUnknown DeferredReason = 0
+
+	// DeferredReasonProviderConfigUnknown represents a deferred reason caused
+	// by unknown provider configuration.
+	DeferredReasonProviderConfigUnknown DeferredReason = 2
+)
+
+// DeferredResponse is used to indicate to Terraform that a resource or data source is not able
+// to be applied yet and should be skipped (deferred). After completing an apply that has deferred actions,
+// the practitioner can then execute additional plan and apply “rounds” to eventually reach convergence
+// where there are no remaining deferred actions.
+type DeferredResponse struct {
+	// Reason represents the deferred reason.
+	Reason DeferredReason
+}
+
+// DeferredReason represents different reasons for deferring a change.
+type DeferredReason int32
+
+func (d DeferredReason) String() string {
+	switch d {
+	case 0:
+		return "Unknown"
+	case 2:
+		return "Provider Config Unknown"
+	}
+	return "Unknown"
+}

helper/schema/grpc_provider.go

@@ -607,12 +607,37 @@ func (s *GRPCProviderServer) ConfigureProvider(ctx context.Context, req *tfproto
 	// request scoped contexts, however this is a large undertaking for very large providers.
 	ctxHack := context.WithValue(ctx, StopContextKey, s.StopContext(context.Background()))
 
+	// NOTE: This is a hack to pass the deferral_allowed field from the Terraform client to the
+	// underlying (provider).Configure function, which cannot be changed because the function
+	// signature is public. (╯°□°)╯︵ ┻━┻
+	s.provider.deferralAllowed = configureDeferralAllowed(req.ClientCapabilities)
+
 	logging.HelperSchemaTrace(ctx, "Calling downstream")
 	diags := s.provider.Configure(ctxHack, config)
 	logging.HelperSchemaTrace(ctx, "Called downstream")
 
 	resp.Diagnostics = convert.AppendProtoDiag(ctx, resp.Diagnostics, diags)
 
+	if s.provider.providerDeferred != nil {
+		// Check if a deferred response was incorrectly set on the provider. This would cause an error during later RPCs.
+		if !configureDeferralAllowed(req.ClientCapabilities) {
+			resp.Diagnostics = append(resp.Diagnostics, &tfprotov5.Diagnostic{
+				Severity: tfprotov5.DiagnosticSeverityError,
+				Summary:  "Invalid Deferred Provider Response",
+				Detail: "Provider configured a deferred response for all resources and data sources but the Terraform request " +
+					"did not indicate support for deferred actions. This is an issue with the provider and should be reported to the provider developers.",
+			})
+		} else {
+			logging.HelperSchemaDebug(
+				ctx,
+				"Provider has configured a deferred response, all associated resources and data sources will automatically return a deferred response.",
+				map[string]interface{}{
+					"deferred_reason": s.provider.providerDeferred.Reason.String(),
+				},
+			)
+		}
+	}
+
 	return resp, nil
 }
 
@@ -632,6 +657,22 @@ func (s *GRPCProviderServer) ReadResource(ctx context.Context, req *tfprotov5.Re
 	}
 	schemaBlock := s.getResourceSchemaBlock(req.TypeName)
 
+	if s.provider.providerDeferred != nil {
+		logging.HelperSchemaDebug(
+			ctx,
+			"Provider has deferred response configured, automatically returning deferred response.",
+			map[string]interface{}{
+				"deferred_reason": s.provider.providerDeferred.Reason.String(),
+			},
+		)
+
+		resp.NewState = req.CurrentState
+		resp.Deferred = &tfprotov5.Deferred{
+			Reason: tfprotov5.DeferredReason(s.provider.providerDeferred.Reason),
+		}
+		return resp, nil
+	}
+
 	stateVal, err := msgpack.Unmarshal(req.CurrentState.MsgPack, schemaBlock.ImpliedType())
 	if err != nil {
 		resp.Diagnostics = convert.AppendProtoDiag(ctx, resp.Diagnostics, err)
@@ -731,6 +772,25 @@ func (s *GRPCProviderServer) PlanResourceChange(ctx context.Context, req *tfprot
 		resp.UnsafeToUseLegacyTypeSystem = true
 	}
 
+	// Provider deferred response is present and the resource hasn't opted-in to CustomizeDiff being called, return early
+	// with proposed new state as a best effort for PlannedState.
+	if s.provider.providerDeferred != nil && !res.ResourceBehavior.ProviderDeferred.EnablePlanModification {
+		logging.HelperSchemaDebug(
+			ctx,
+			"Provider has deferred response configured, automatically returning deferred response.",
+			map[string]interface{}{
+				"deferred_reason": s.provider.providerDeferred.Reason.String(),
+			},
+		)
+
+		resp.PlannedState = req.ProposedNewState
+		resp.PlannedPrivate = req.PriorPrivate
+		resp.Deferred = &tfprotov5.Deferred{
+			Reason: tfprotov5.DeferredReason(s.provider.providerDeferred.Reason),
+		}
+		return resp, nil
+	}
+
 	priorStateVal, err := msgpack.Unmarshal(req.PriorState.MsgPack, schemaBlock.ImpliedType())
 	if err != nil {
 		resp.Diagnostics = convert.AppendProtoDiag(ctx, resp.Diagnostics, err)
@@ -951,6 +1011,21 @@ func (s *GRPCProviderServer) PlanResourceChange(ctx context.Context, req *tfprot
 		resp.RequiresReplace = append(resp.RequiresReplace, pathToAttributePath(p))
 	}
 
+	// Provider deferred response is present, add the deferred response alongside the provider-modified plan
+	if s.provider.providerDeferred != nil {
+		logging.HelperSchemaDebug(
+			ctx,
+			"Provider has deferred response configured, returning deferred response with modified plan.",
+			map[string]interface{}{
+				"deferred_reason": s.provider.providerDeferred.Reason.String(),
+			},
+		)
+
+		resp.Deferred = &tfprotov5.Deferred{
+			Reason: tfprotov5.DeferredReason(s.provider.providerDeferred.Reason),
+		}
+	}
+
 	return resp, nil
 }
 
@@ -1145,6 +1220,60 @@ func (s *GRPCProviderServer) ImportResourceState(ctx context.Context, req *tfpro
 		Type: req.TypeName,
 	}
 
+	if s.provider.providerDeferred != nil {
+		logging.HelperSchemaDebug(
+			ctx,
+			"Provider has deferred response configured, automatically returning deferred response.",
+			map[string]interface{}{
+				"deferred_reason": s.provider.providerDeferred.Reason.String(),
+			},
+		)
+
+		// The logic for ensuring the resource type is supported by this provider is inside of (provider).ImportState
+		// We need to check to ensure the resource type is supported before using the schema
+		_, ok := s.provider.ResourcesMap[req.TypeName]
+		if !ok {
+			resp.Diagnostics = convert.AppendProtoDiag(ctx, resp.Diagnostics, fmt.Errorf("unknown resource type: %s", req.TypeName))
+			return resp, nil
+		}
+
+		// TODO: We need to make a decision on how we want to handle this scenario. If a deferral is happening for an import
+		// because of PROVIDER_CONFIG_UNKNOWN, the returned import object will still be in the rendered output in the plan
+		// (when using new import blocks)
+		//
+		// We can:
+		// - Send back an unknown value (preferred by core because it semantically makes sense)
+		// - Send back a null value (matches the general behavior of import today, i.e. fill what you can, rest are null)
+		//
+		// Regardless of what we send back, Core will send nulls to future "ApplyResourceChange" RPC calls to keep compatibility
+		// since "Update" methods of providers are not meant to receive Unknown values.
+		//
+		// The current approach below sends back an unknown value
+		//
+		schemaBlock := s.getResourceSchemaBlock(req.TypeName)
+		unknownVal := cty.UnknownVal(schemaBlock.ImpliedType())
+		unknownStateMp, err := msgpack.Marshal(unknownVal, schemaBlock.ImpliedType())
+		if err != nil {
+			resp.Diagnostics = convert.AppendProtoDiag(ctx, resp.Diagnostics, err)
+			return resp, nil
+		}
+
+		resp.ImportedResources = []*tfprotov5.ImportedResource{
+			{
+				TypeName: req.TypeName,
+				State: &tfprotov5.DynamicValue{
+					MsgPack: unknownStateMp,
+				},
+			},
+		}
+
+		resp.Deferred = &tfprotov5.Deferred{
+			Reason: tfprotov5.DeferredReason(s.provider.providerDeferred.Reason),
+		}
+
+		return resp, nil
+	}
+
 	newInstanceStates, err := s.provider.ImportState(ctx, info, req.ID)
 	if err != nil {
 		resp.Diagnostics = convert.AppendProtoDiag(ctx, resp.Diagnostics, err)
@@ -1254,6 +1383,32 @@ func (s *GRPCProviderServer) ReadDataSource(ctx context.Context, req *tfprotov5.
 
 	schemaBlock := s.getDatasourceSchemaBlock(req.TypeName)
 
+	if s.provider.providerDeferred != nil {
+		logging.HelperSchemaDebug(
+			ctx,
+			"Provider has deferred response configured, automatically returning deferred response.",
+			map[string]interface{}{
+				"deferred_reason": s.provider.providerDeferred.Reason.String(),
+			},
+		)
+
+		// Send an unknown value for the data source
+		unknownVal := cty.UnknownVal(schemaBlock.ImpliedType())
+		unknownStateMp, err := msgpack.Marshal(unknownVal, schemaBlock.ImpliedType())
+		if err != nil {
+			resp.Diagnostics = convert.AppendProtoDiag(ctx, resp.Diagnostics, err)
+			return resp, nil
+		}
+
+		resp.State = &tfprotov5.DynamicValue{
+			MsgPack: unknownStateMp,
+		}
+		resp.Deferred = &tfprotov5.Deferred{
+			Reason: tfprotov5.DeferredReason(s.provider.providerDeferred.Reason),
+		}
+		return resp, nil
+	}
+
 	configVal, err := msgpack.Unmarshal(req.Config.MsgPack, schemaBlock.ImpliedType())
 	if err != nil {
 		resp.Diagnostics = convert.AppendProtoDiag(ctx, resp.Diagnostics, err)
@@ -1674,3 +1829,14 @@ func validateConfigNulls(ctx context.Context, v cty.Value, path cty.Path) []*tfp
 
 	return diags
 }
+
+// Helper function that check a ConfigureProviderClientCapabilities struct to determine if a deferred response can be
+// returned to the Terraform client. If no ConfigureProviderClientCapabilities have been passed from the client, then false
+// is returned.
+func configureDeferralAllowed(in *tfprotov5.ConfigureProviderClientCapabilities) bool {
+	if in == nil {
+		return false
+	}
+
+	return in.DeferralAllowed
+}