How-to: Import Block Basics

Introduction

Before the release of Terraform v1.5.0, the primary method to import resources into the Terraform state was by executing the terraform import CLI command.

Terraform versions 1.5.0 and later support import blocks coded directly in the configuration. This method, often called "plannable import" or "config-driven import," allows you to generate the resource configuration, review it, and resolve any errors before Terraform writes the resource to the state file.

Expected Outcome

By the end of this guide, you will successfully import an existing AWS resource into your Terraform state using an import block and integrate its configuration into your project.

Prerequisites

• Terraform v1.5.0 or later installed.
• An AWS account with credentials configured for CLI access.
• An HCP Terraform account and an existing workspace.

Procedure

This procedure demonstrates importing an aws_ebs_volume resource.

1. Configure Environment and HCP Terraform Integration

First, on your local machine, authenticate to AWS and to HCP Terraform.

Next, configure your HCP Terraform workspace with your AWS credentials. Navigate to your workspace settings and configure AWS_REGION, AWS_ACCESS_KEY_ID, and AWS_SECRET_ACCESS_KEY as workspace variables.

In your local Terraform configuration directory, set up the HCP Terraform cloud integration and run terraform init.

2. Create the AWS Resource Manually

For an import to work, the resource must exist in your cloud provider but not in your Terraform state file.

Verify the resource does not already exist in your state by running the following command.

$ terraform state show aws_ebs_volume.test

You should see the output No instance found for the given address!.

Next, create the test EBS volume in AWS using the AWS CLI.

$ aws ec2 create-volume \
  --availability-zone <YOUR_AVAILABILITY_ZONE> \
  --volume-type gp2 \
  --size 10 \
  --tag-specifications 'ResourceType=volume,Tags=[{Key=Name,Value=test-volume}]'

A successful creation returns information about the EBS volume. Note the VolumeId, as you will need it in the next step.

{
    "AvailabilityZone": "...",
    "CreateTime": "...",
    "Encrypted": false,
    "Size": 10,
    "SnapshotId": "",
    "State": "creating",
    "VolumeId": "vol-xxxxxxxxxx",
    ##...
}

3. Define the import Block

According to the aws_ebs_volume documentation, you must use the VolumeId to import this resource. In your Terraform configuration (e.g., main.tf), add the following import block, replacing the placeholder with your volume ID.

import {
  to = aws_ebs_volume.test
  id = "vol-xxxxxxxxxx"
}

4. Generate the Configuration and Plan

To begin the import process, run terraform plan with the -generate-config-out flag. This command tells Terraform to generate the configuration for the imported resource and save it to a new file named generated.tf.

$ terraform plan -generate-config-out=generated.tf

After the command runs, review the plan output. Notice that the plan fails, and the resource has not yet been imported into the state.

Waiting for the plan to start...

Terraform v1.5.0
on linux_amd64

Initializing plugins and modules...
aws_ebs_volume.test: Preparing import... [id=vol-xxxxxxxxxx]
aws_ebs_volume.test: Refreshing state... [id=vol-xxxxxxxxxx]

Planning failed. Terraform encountered an error while generating this plan.

╷
│ Error: expected throughput to be in the range (125 - 1000), got 0
│ 
│ with aws_ebs_volume.test,
│ on generated-run-pf4BSTKYEs2ERbFG.tf line 16:
│ (source code not available)
│ 
╵
Operation failed: failed running terraform plan (exit 1)

You can confirm this by running terraform state show aws_ebs_volume.test again. The output will still be No instance found for the given address!.

5. Resolve Configuration Errors

To resolve the error, open the newly created generated.tf file. The error message indicates an issue with the throughput argument. In this example, you can resolve it by commenting out or removing the line throughput = 0 from the file.

6. Apply the Import Plan

After correcting the configuration in generated.tf, run terraform apply.

$ terraform apply

The output will show Plan: 1 to import and conclude with Apply complete! Resources: 1 imported.

7. Verify the Import

To confirm the resource is now in your state file, run the state show command one more time.

$ terraform state show aws_ebs_volume.test

This time, the command will display the state object for the imported resource.

8. Clean Up the Configuration

To finalize the process, move the aws_ebs_volume resource block from generated.tf into your main configuration file (e.g., main.tf) and delete the generated.tf file.

It is also a best practice to remove the import block from your configuration, as it is no longer needed after a successful import. If you use a Version Control System (VCS), commit your updated configuration files.