How to Use Terraform Import Block for Importing Resources

With Terraform 1.5 and later, you can use the import block to manage the import of resources directly in your configuration. This feature simplifies the process of importing existing infrastructure into Terraform state, eliminating the need for a separate CLI terraform import command.

In this article, we explain the import block and how to use it to import different resources.

What Is a Terraform Import Block?

The Terraform import block introduced in Terraform v1.5.0 provides a declarative approach for importing existing infrastructure resources into a Terraform state file. It allows resource imports to become an integral part of Terraform’s planning process — similar to other managed resources — rather than being treated as a direct state operation. 

As a result, the import block improves transparency and aligns resource imports with the core principles of infrastructure as code (IaC), enabling users to manage their infrastructure more effectively and predictably. 

The syntax for an import block in Terraform is as follows:

import {
  to = <resource_address>
  id = <resource_identifier>
}

• to: Specifies the resource address in your configuration where the imported resource will be mapped. 
• id: Defines the unique identifier of the existing resource in the provider’s API. Ensure that your Terraform provider is correctly configured to access the resource being imported.

Note that some resource types may have additional requirements or constraints for importing.

Import Block vs. Terraform Import Command

An import block in Terraform lets you define resources directly in your configuration file, simplifying the management of existing infrastructure.

In contrast, when the terraform import command is used without an import block, it links an existing resource to the Terraform state but does not automatically generate the corresponding configuration in your code. You must manually add this configuration afterward. The import command is particularly useful for one-time imports or transitioning infrastructure into Terraform management.

Both methods require careful handling to ensure consistency between the Terraform state and the actual infrastructure. Import blocks are generally better suited for ongoing resource management, whereas the standalone command works well for occasional imports.

Example 1: Using Terraform Import Block to Import an S3 Bucket

Let’s suppose we have an existing AWS S3 bucket (my-existing-bucket) that you want to manage with Terraform.

The resource block specifies the S3 bucket (aws_s3_bucket.example) and the bucket attribute defines the name of the existing bucket:

resource "aws_s3_bucket" "example" {
  bucket = "my-existing-bucket"
}

import {
  to = aws_s3_bucket.example
  id = "my-existing-bucket"
}

The import block links the existing S3 bucket to the Terraform resource. 

• to: Maps the imported resource to the address of the resource block (aws_s3_bucket.example)
• id: Specifies the unique ID of the bucket (my-existing-bucket).

When you run terraform plan, Terraform reads the import block, checks the state of the existing S3 bucket, and shows a preview of the changes it will make to the state file. Then, after we run terraform apply, Terraform updates the state file to include the existing bucket, mapping it to the aws_s3_bucket.example resource.

After running terraform apply and successfully importing the resource, it is a best practice to remove the import block. Keeping it won’t cause any harm, but removing it helps maintain a clean configuration and minimizes potential confusion during future state management.

Example 2: Using Terraform Import Block to Import an EC2 Instance

Let’s consider another example: We have an existing EC2 instance with the ID i-1234567890abcdef0 and want to bring it under Terraform management.

We define the aws_instance resource we want Terraform to manage in the resource block. Make sure the attributes (e.g., ami, instance_type) match the existing instance’s configuration:

resource "aws_instance" "example" {
  ami           = "ami-0abcdef1234567890"  # Replace with the actual AMI ID
  instance_type = "t2.micro"
}

import {
  to = aws_instance.example
  id = "i-1234567890abcdef0"
}

In the import block:

• to: Maps the resource in your configuration (aws_instance.example) to the existing resource.
• id: Specifies the unique ID of the EC2 instance you are importing.

Once you add the resource block and the import statement to your Terraform configuration file, run terraform plan to preview the changes. Next, run terraform apply to import the resource into Terraform’s state file.

After the import, Terraform will manage the existing EC2 instance, ensuring its configuration remains declarative.

Example 3: Using Terraform Import Block to Import an Azure Resource Group

In the next example, we will be importing an Azure resource group.

We have an existing Azure resource group named example-resource-group in the East US region, and we want to manage it with Terraform.

First, in the resource block, we define the azurerm_resource_group resource that Terraform will manage:

resource "azurerm_resource_group" "example" {
  name     = "example-resource-group"
  location = "East US"
}

import {
  to = azurerm_resource_group.example
  id = "/subscriptions/<subscription_id>/resourceGroups/example-resource-group"
}

The import block:

• to: Maps the resource in your configuration (azurerm_resource_group.example) to the existing Azure resource.
• id: Specifies the fully qualified Azure resource ID of the resource group. Remember to replace <subscription_id> with your actual subscription ID.

Add the resource and the import block to your Terraform configuration file. Next, run the terraform plan command to preview the changes and execute terraform apply to apply the changes and import the resource into Terraform’s state file.

Can You Use the Terraform Import Block Conditionally?

The Terraform import block is designed to be declarative and requires specific values known at plan time. Therefore, it cannot be used conditionally within your Terraform code. 

The import block does not support dynamic expressions or variables for determining the import ID based on conditions. Attempts to use constructs like count or variables within the import block will result in errors, as Terraform does not allow such arguments in this context.

Key Points

The introduction of the import block in Terraform 1.5+ simplifies resource management by enabling the direct import and definition of resources within configuration files. It aligns with IaC principles by reducing complexity and making it easier to integrate existing infrastructure into Terraform configurations.