Import

Practitioners can use the terraform import command to let Terraform begin managing existing infrastructure by importing an existing resource into their Terraform project's state. A resource's importer function implements the logic to add a resource to Terraform's state. Refer to Resources - Import in the Framework documentation for details.

This page explains how to migrate import functions from SDKv2 to the plugin Framework.

SDKv2

In SDKv2, the Importer field on the schema.Resource defines how the provider imports resources to Terraform's state. The following example implements resource import with SDKv2.

func resourceExample() *schema.Resource {
    return &schema.Resource{
        Importer: &schema.ResourceImporter{
            StateContext: StateContextFunc,
        },
        /* ... */

The StateContextFunc is the function called to import a resource into Terraform state. Any operations that are needed to import the resource take place within this function and may result in the mutation of the ResourceData that is passed into the function. The return value is a slice of schema.ResourceData. This slice might be as simple as returning the ResourceData that was passed into the function, or it may involve multiple fan out to multiple resources, such as AWS security groups.

Framework

In the Framework, you implement the ResourceWithImportState interface on your resource.Resource type to allow users to import a given resource. This interface requires that your type implement a ImportState function.

The following code shows how you define an ImportState function with the Framework.

func (r *resourceExample) ImportState(ctx context.Context, req resource.ImportStateRequest, resp *resource.ImportStateResponse) {
    /* ... */
}

The ImportState function includes a resource.ImportStateResponse, which you use to set your resource's state.

Migration Notes

Remember the following differences between SDKv2 and the Framework when completing the migration.

• In both SDKv2 and Framework, there is no access to the configuration, state, or plan during import. The import functions can only access the value (e.g., the resource's ID) supplied to the terraform import command.
• In SDKv2, you implement resource importing by populating the Importer field on the schema.Resource struct. In the Framework, you define an ImportState function on the type which implements resource.Resource. This implementation satisfies the resource.ResourceWithImportState interface.

Example

In the simple use case in which schema.ImportStatePassthroughContext has been used with SDKv2, migrating to the Framework involves using the resource.ImportStatePassthroughID function.

SDKv2

func resourceExample() *schema.Resource {
    return &schema.Resource{
        Importer: &schema.ResourceImporter{
            StateContext: schema.ImportStatePassthroughContext,
        },
        /* ... */
    }
}

Framework

func (r *resourceExample) ImportState(ctx context.Context, req resource.ImportStateRequest, resp *resource.ImportStateResponse) {
    resource.ImportStatePassthroughID(ctx, path.Root("id"), req, resp)
}

This example also shows one way to handle populating attributes with their default values during import.

SDKv2

The following example shows the import function for the example_resource resource with SDKv2.

func exampleResource() *schema.Resource {
    return &schema.Resource{
        Importer: &schema.ResourceImporter{
            StateContext: importFunc,
        },
        /* ... */
    }
}

The following example shows the implementation of the importFunc function with SDKv2.

func importFunc(ctx context.Context, d *schema.ResourceData, meta interface{}) ([]*schema.ResourceData, error) {
    d.SetId("id")

    if err := d.Set("attribute", "value"); err != nil {
        return nil, fmt.Errorf("resource example import failed, error setting attribute: %w", err)
    }

    return []*schema.ResourceData{d}, nil
}

Framework

The following shows the same section of provider code after the migration.

This code implements the ResourceWithImportState interface on the exampleResource type by defining an ImportState function.

func (r *exampleResource) ImportState(ctx context.Context, req resource.ImportStateRequest, resp *resource.ImportStateResponse) {
    id := req.ID

    state := exampleModel{
        ID:         types.StringValue("id"),
        Attribute:  types.StringValue("value"),
    }

    diags := resp.State.Set(ctx, &state)
    resp.Diagnostics.Append(diags...)
    if resp.Diagnostics.HasError() {
        return
    }
}