Terraform Import: What It Is and How to Use It

In this post we’ll explore Terraform Import, a powerful command-line tool that allows you to bring existing infrastructure under Terraform management. We’ll cover what Terraform Import is, its common use cases, and how to use it effectively. Additionally, we’ll discuss some limitations you should be aware of when using Terraform Import.  

Whether new to Terraform or an experienced user, this guide will help you understand and leverage Terraform Import to manage your infrastructure better.

What Is Terraform?

Terraform is an open-source infrastructure as code (IaC) tool developed by HashiCorp that enables you to define, provide, and manage infrastructure resources using a declarative configuration language called HashiCorp Configuration Language (HCL).  

With Terraform, you can automate the creation, modification, and management of infrastructure resources across various cloud providers, such as Amazon Web Services (AWS), Google Cloud Platform (GCP), Microsoft Azure, and many others.  By using Terraform, you can streamline your infrastructure management, ensure consistency, and reduce human error, making it an essential tool for modern DevOps practices. 

What Is Terraform Import?

Terraform Import is a powerful command-line tool provided by Terraform that allows you to import existing infrastructure into your Terraform state. This is particularly useful when you have resources created outside of Terraform, or when you’re adopting Terraform for the first time and need to bring your existing infrastructure under its management. 

Using Terraform Import, you can import resources from multiple cloud providers. Once imported, these resources can be managed using Terraform configurations, making it easy to version control, collaborate, and automate your infrastructure. 

Why Use Terraform Import?

There are several common use cases for using Terraform Import, which are outlined below: 

1. Adopting Terraform for existing infrastructure: If you’re starting to use it and already have resources created outside of it, you’ll need a way to bring those resources under its control. Importing these resources allows you to do that, enabling you to manage them with Terraform.
2. Migrating resources between Terraform projects: Sometimes you may need to move resources between different Terraform projects or environments. You can ensure resources are managed correctly and consistently by importing resources into a new project.
3. Recovering lost state: In cases where your Terraform state file is lost or corrupted, you can use Terraform Import to recover the state of your infrastructure. You can recreate the lost information by importing resources back into a new state file and continue managing your infrastructure with Terraform.

Importing resources into Terraform essentially means adding existing infrastructure components, such as virtual machines or databases, to your Terraform state file. This allows you to manage these resources with Terraform configurations, just like you would if they were created by Terraform initially. 

How to Use Terraform Import

Before diving into the process of using Terraform Import, make sure you have Terraform installed on your machine and are familiar with its basic concepts, such as providers, resources, and state files. Here’s a step-by-step guide on how to use Terraform Import: 

Identify the Resources You Want to Import

List the resources you want to import, along with their respective IDs or ARNs (Amazon Resource Names) for AWS or equivalent identifiers for other providers. 

Create a Terraform Configuration File

Write a Terraform configuration file (.tf) that includes the provider and resources you want to import. Be sure to define the resources with the same types and names as those you import. For example, if you’re importing an AWS EC2 instance, your configuration file should include a resource block for aws_instance. 

Run Terraform Init

Execute the terraform init command in your terminal to initialize your Terraform working directory. This will download the necessary provider plugins and set up the backend for storing your Terraform state. 

Run Terraform Import

Use the terraform import command, followed by the resource type and name, and then the resource identifier. For example, if you’re importing an AWS EC2 instance with the ID i-1234567890abcdef0, the command would look like this: 

terraform import aws_instance.example i-1234567890abcdef0

Replace aws_instance.example with the appropriate resource type and name from your configuration file and i-1234567890abcdef0 with the actual resource identifier. 

Verify the Import

After the import is complete, run terraform show to view the state of your imported resources. Check that the details match the resources you intended to import. If everything looks correct, you’ve successfully imported the resources into your Terraform state. 

Adjust Your Configuration

You should fine-tune your Terraform configuration file to match the actual settings of the imported resources. Then, update the resource blocks to reflect the desired configuration, ensuring they match the imported state. 

Run Terraform Plan

Execute terraform plan to compare your updated configuration with the imported state. If there are any discrepancies, review and adjust your configuration file until there are no unexpected changes. 

Apply Your Configuration

Once you’re satisfied with the configuration and the planned output, run terraform apply to apply your configuration and make any necessary changes to the imported resources. 

Your resources are now fully managed by Terraform. Remember that Terraform Import can also be used with for_each, modules, and various resource types. When importing resources that were created with for_each, be sure to specify the correct key in the terraform import command. For example: 

terraform import 'aws_instance.example["key"]' i-1234567890abcdef0

Include the module path in the resource reference when importing resources within a module. For example:

terraform import module.my_module.aws_instance.example i-1234567890abcdef0

What Are the Limitations of Terraform Import?

While Terraform Import is an incredibly helpful tool, there are some limitations to be aware of: 

1. Not all resources can be imported: Some resources or resource types might not support importing. Check the Terraform provider documentation to determine if the specific resources you want to import are supported.
2. Manual configuration updates: After importing resources, you’ll need to manually update your Terraform configuration file to match the actual state of the imported resources. This can be time-consuming, especially for complex resources with many attributes.
3. Single resource imports: Terraform Import currently only supports importing one resource at a time. You must run the terraform import command for each resource separately if you need to import multiple resources.
4. No automated import: Terraform does not automatically discover and import resources. You must provide the resource type, name, and identifier for each resource you want to import.

Despite these limitations, Terraform Import remains a valuable tool for bringing existing infrastructure under Terraform management or recovering lost state. By understanding its capabilities and limitations, you can use Terraform Import effectively to manage your infrastructure with confidence. 

In Summary

Terraform Import is a valuable tool that helps you bring existing infrastructure under Terraform management, making it easier to maintain and automate your resources. While there are some limitations to be aware of, understanding its use cases, capabilities, and how to use it effectively can significantly enhance your Terraform experience.  

If you’re new to Terraform or moving resources from one project to another, Terraform Import can simplify your infrastructure management and help you fully utilize the benefits of infrastructure as code. 

This post was written by Juan Reyes. As an entrepreneur, skilled engineer, and mental health champion, Juan pursues sustainable self-growth, embodying leadership, wit, and passion. With over 15 years of experience in the tech industry, Juan has had the opportunity to work with some of the most prominent players in mobile development, web development, and e-commerce in Japan and the US.