How-to: Import Block Basics

Background

Before the release of Terraform v1.5.0, the only way to import resources into terraform.tfstate was to execute the CLI command terraform import [options] ADDRESS_ID [a]. 

Now, Terraform versions >=1.5.0 support import blocks coded directly in the configuration [b]. This method of importing resources is often called "plannable import" or "config-driven import". With import blocks, you must review your generated configuration and resolve all errors before the resource will be written to state. Please see the example below.

Example Import with Terraform Cloud Backend

Setup

First, on your local machine, authenticate to AWS and to Terraform Cloud (TFC). Push your credentials to your workspace. For this example, I went to my TFC workspace and configured AWS_REGION, AWS_ACCESS_KEY_ID, and AWS_SECRET_ACCESS_KEY as workspace variables [c]. 

Back on your local machine, setup your cloud backend [d] and execute terraform init.

We will be importing one aws_ebs_volume resource named "test" to state. To make sure this resource does not already exist in your state file, execute terraform state show aws_ebs_volume.test [e]. You should see "No instance found for the given address!".

Create EBS volume in AWS

For import to work, the resource must exist in AWS but not in your state file. Let's create the test resource in AWS using the aws cli [f]:

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

Successful creation returns information about the EBS volume. Note the volume ID as you will need it in subsequent steps "VolumeId": "vol-xxxxxxxxxx".

Configure the Import Block

According to the aws_ebs_volume documentation, we will use the VolumeId to import this resource [g]. In your Terraform configuration, add the following lines of code:

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

Execute Plan and Review Generated Config

In order to begin import, please execute terraform plan -generate-config-out=generated.tf. After successful execution, you will need to review the contents of generated.tf.

Notice, the plan errored and the resource has not been imported into state. You can confirm this by executing terraform state show aws_ebs_volume.test. Again, you will see "No instance found for the given address!".

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)

Resolve Errors and Execute Apply

To resolve, read the error message(s). In this example, I navigated to generated.tf and commented out the argument throughput = 0, then executed terraform apply. 

You will see "Plan: 1 to import" and "Apply complete! Resources: 1 imported". 

To confirm, execute terraform state show aws_ebs_volume.test. You will see the state object. 

Cleanup Configuration

To cleanup, add the aws_ebs_volume code block to your main configuration files (e.g., main.tf) and delete generated.tf. I also recommend deleting the import block since it is no longer necessary. If you are using VCS, commit new changes.

Destruction and Deletion

If you want to delete aws_ebs_volume.test from AWS, your configuration, and your state file, all you have to do is comment out or delete the lines of code for aws_ebs_volume.test and execute terraform apply. 

Links

[a] https://developer.hashicorp.com/terraform/cli/commands/import

[b] https://developer.hashicorp.com/terraform/language/import 

[c] https://registry.terraform.io/providers/hashicorp/aws/latest/docs#environment-variables 

[d] https://developer.hashicorp.com/terraform/cli/cloud/settings 

[e] https://developer.hashicorp.com/terraform/cli/commands/state/show 

[f] https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ec2/create-volume.html 

[g] https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/ebs_volume#import