tfsdk: Initial ImportResourceState support

.changelog/149.txt

@@ -0,0 +1,7 @@
+```release-note:breaking-change
+tfsdk: `Resource` implementations must now include the `ImportState(context.Context, ImportResourceStateRequest, *ImportResourceStateResponse)` method. If import is not supported, call the `ResourceImportStateNotImplemented()` function or return an error.
+```
+
+```release-note:feature
+tfsdk: Support resource import
+```

tfsdk/request_import.go

@@ -0,0 +1,14 @@
+package tfsdk
+
+// ImportResourceStateRequest represents a request for the provider to import a
+// resource. An instance of this request struct is supplied as an argument to
+// the Resource's ImportState method.
+type ImportResourceStateRequest struct {
+	// ID represents the import identifier supplied by the practitioner when
+	// calling the import command. In many cases, this may align with the
+	// unique identifier for the resource, which can optionally be stored
+	// as an Attribute. However, this identifier can also be treated as
+	// its own type of value and parsed during import. This value
+	// is not stored in the state unless the provider explicitly stores it.
+	ID string
+}

tfsdk/resource.go

@@ -41,6 +41,15 @@ type Resource interface {
 	// Delete is called when the provider must delete the resource. Config
 	// values may be read from the DeleteResourceRequest.
 	Delete(context.Context, DeleteResourceRequest, *DeleteResourceResponse)
+
+	// ImportState is called when the provider must import the resource.
+	//
+	// If import is not supported, it is recommended to use the
+	// ResourceImportStateNotImplemented() call in this method.
+	//
+	// If setting an attribute with the import identifier, it is recommended
+	// to use the ResourceImportStatePassthroughID() call in this method.
+	ImportState(context.Context, ImportResourceStateRequest, *ImportResourceStateResponse)
 }
 
 // ResourceWithModifyPlan represents a resource instance with a ModifyPlan

tfsdk/resource_import.go

@@ -0,0 +1,37 @@
+package tfsdk
+
+import (
+	"context"
+
+	"github.com/hashicorp/terraform-plugin-go/tftypes"
+)
+
+// ResourceImportStateNotImplemented is a helper function to return an error
+// diagnostic about the resource not supporting import. The details defaults
+// to a generic message to contact the provider developer, but can be
+// customized to provide specific information or recommendations.
+func ResourceImportStateNotImplemented(ctx context.Context, details string, resp *ImportResourceStateResponse) {
+	if details == "" {
+		details = "This resource does not support import. Please contact the provider developer for additional information."
+	}
+
+	resp.Diagnostics.AddError(
+		"Resource Import Not Implemented",
+		details,
+	)
+}
+
+// ResourceImportStatePassthroughID is a helper function to set the import
+// identifier to a given state attribute path. The attribute must accept a
+// string value.
+func ResourceImportStatePassthroughID(ctx context.Context, path *tftypes.AttributePath, req ImportResourceStateRequest, resp *ImportResourceStateResponse) {
+	if path == nil || tftypes.NewAttributePath().Equal(path) {
+		resp.Diagnostics.AddError(
+			"Resource Import Passthrough Missing Attribute Path",
+			"This is always an error in the provider. Please report the following to the provider developer:\n\n"+
+				"Resource ImportState method call to ResourceImportStatePassthroughID path must be set to a valid attribute path that can accept a string value.",
+		)
+	}
+
+	resp.Diagnostics.Append(resp.State.SetAttribute(ctx, path, req.ID)...)
+}

tfsdk/response_import.go

@@ -0,0 +1,21 @@
+package tfsdk
+
+import (
+	"github.com/hashicorp/terraform-plugin-framework/diag"
+)
+
+// ImportResourceStateResponse represents a response to a ImportResourceStateRequest.
+// An instance of this response struct is supplied as an argument to the
+// Resource's ImportState method, in which the provider should set values on
+// the ImportResourceStateResponse as appropriate.
+type ImportResourceStateResponse struct {
+	// Diagnostics report errors or warnings related to importing the
+	// resource. An empty slice indicates a successful operation with no
+	// warnings or errors generated.
+	Diagnostics diag.Diagnostics
+
+	// State is the state of the resource following the import operation.
+	// It must contain enough information so Terraform can successfully
+	// refresh the resource, e.g. call the Resource Read method.
+	State State
+}

tfsdk/serve.go

@@ -1122,14 +1122,6 @@ func (s *server) applyResourceChange(ctx context.Context, req *tfprotov6.ApplyRe
 	}
 }
 
-func (s *server) ImportResourceState(ctx context.Context, _ *tfprotov6.ImportResourceStateRequest) (*tfprotov6.ImportResourceStateResponse, error) {
-	// uncomment when we implement this function
-	//ctx = s.registerContext(ctx)
-
-	// TODO: support resource importing
-	return &tfprotov6.ImportResourceStateResponse{}, nil
-}
-
 // validateDataResourceConfigResponse is a thin abstraction to allow native Diagnostics usage
 type validateDataResourceConfigResponse struct {
 	Diagnostics diag.Diagnostics

tfsdk/serve_data_source_config_validators_test.go

@@ -60,6 +60,7 @@ type testServeDataSourceConfigValidators struct {
 }
 
 func (r testServeDataSourceConfigValidators) Read(ctx context.Context, req ReadDataSourceRequest, resp *ReadDataSourceResponse) {
+	// Intentionally blank. Not expected to be called during testing.
 }
 
 func (r testServeDataSourceConfigValidators) ConfigValidators(ctx context.Context) []DataSourceConfigValidator {

tfsdk/serve_data_source_validate_config_test.go

@@ -60,6 +60,7 @@ type testServeDataSourceValidateConfig struct {
 }
 
 func (r testServeDataSourceValidateConfig) Read(ctx context.Context, req ReadDataSourceRequest, resp *ReadDataSourceResponse) {
+	// Intentionally blank. Not expected to be called during testing.
 }
 
 func (r testServeDataSourceValidateConfig) ValidateConfig(ctx context.Context, req ValidateDataSourceConfigRequest, resp *ValidateDataSourceConfigResponse) {

tfsdk/serve_import.go

@@ -0,0 +1,128 @@
+package tfsdk
+
+import (
+	"context"
+
+	"github.com/hashicorp/terraform-plugin-framework/diag"
+	"github.com/hashicorp/terraform-plugin-go/tfprotov6"
+	"github.com/hashicorp/terraform-plugin-go/tftypes"
+)
+
+// importedResource represents a resource that was imported.
+//
+// This type is not exported as the framework import implementation is
+// currently designed for the most common use case of single resource import.
+type importedResource struct {
+	Private  []byte
+	State    State
+	TypeName string
+}
+
+func (r importedResource) toTfprotov6(ctx context.Context) (*tfprotov6.ImportedResource, diag.Diagnostics) {
+	var diags diag.Diagnostics
+	irProto6 := &tfprotov6.ImportedResource{
+		Private:  r.Private,
+		TypeName: r.TypeName,
+	}
+
+	stateProto6, err := tfprotov6.NewDynamicValue(r.State.Schema.TerraformType(ctx), r.State.Raw)
+
+	if err != nil {
+		diags.AddError(
+			"Error converting imported resource response",
+			"An unexpected error was encountered when converting the imported resource response to a usable type. This is always a problem with the provider. Please give the following information to the provider developer:\n\n"+err.Error(),
+		)
+		return nil, diags
+	}
+
+	irProto6.State = &stateProto6
+
+	return irProto6, diags
+}
+
+// importResourceStateResponse is a thin abstraction to allow native Diagnostics usage
+type importResourceStateResponse struct {
+	Diagnostics       diag.Diagnostics
+	ImportedResources []importedResource
+}
+
+func (r importResourceStateResponse) toTfprotov6(ctx context.Context) *tfprotov6.ImportResourceStateResponse {
+	resp := &tfprotov6.ImportResourceStateResponse{
+		Diagnostics: r.Diagnostics.ToTfprotov6Diagnostics(),
+	}
+
+	for _, ir := range r.ImportedResources {
+		irProto6, diags := ir.toTfprotov6(ctx)
+		resp.Diagnostics = append(resp.Diagnostics, diags.ToTfprotov6Diagnostics()...)
+		resp.ImportedResources = append(resp.ImportedResources, irProto6)
+	}
+
+	return resp
+}
+
+func (s *server) importResourceState(ctx context.Context, req *tfprotov6.ImportResourceStateRequest, resp *importResourceStateResponse) {
+	resourceType, diags := s.getResourceType(ctx, req.TypeName)
+	resp.Diagnostics.Append(diags...)
+
+	if resp.Diagnostics.HasError() {
+		return
+	}
+
+	resourceSchema, diags := resourceType.GetSchema(ctx)
+	resp.Diagnostics.Append(diags...)
+
+	if resp.Diagnostics.HasError() {
+		return
+	}
+
+	resource, diags := resourceType.NewResource(ctx, s.p)
+	resp.Diagnostics.Append(diags...)
+
+	if resp.Diagnostics.HasError() {
+		return
+	}
+
+	emptyState := tftypes.NewValue(resourceSchema.TerraformType(ctx), nil)
+	importReq := ImportResourceStateRequest{
+		ID: req.ID,
+	}
+	importResp := ImportResourceStateResponse{
+		State: State{
+			Raw:    emptyState,
+			Schema: resourceSchema,
+		},
+	}
+
+	resource.ImportState(ctx, importReq, &importResp)
+	resp.Diagnostics.Append(importResp.Diagnostics...)
+
+	if resp.Diagnostics.HasError() {
+		return
+	}
+
+	if importResp.State.Raw.Equal(emptyState) {
+		resp.Diagnostics.AddError(
+			"Missing Resource Import State",
+			"An unexpected error was encountered when importing the resource. This is always a problem with the provider. Please give the following information to the provider developer:\n\n"+
+				"Resource ImportState method returned no State in response. If import is intentionally not supported, call the ResourceImportStateNotImplemented() function or return an error.",
+		)
+		return
+	}
+
+	resp.ImportedResources = []importedResource{
+		{
+			State:    importResp.State,
+			TypeName: req.TypeName,
+		},
+	}
+}
+
+// ImportResourceState satisfies the tfprotov6.ProviderServer interface.
+func (s *server) ImportResourceState(ctx context.Context, req *tfprotov6.ImportResourceStateRequest) (*tfprotov6.ImportResourceStateResponse, error) {
+	ctx = s.registerContext(ctx)
+	resp := &importResourceStateResponse{}
+
+	s.importResourceState(ctx, req, resp)
+
+	return resp.toTfprotov6(ctx), nil
+}