Terraform Import: Bridging the Gap Between Existing Resources and IaC

terraform import explained

In the world of Infrastructure as Code (IaC), Terraform is a powerful tool that allows you to define and manage cloud resources through declarative configurations. But what happens when you have pre-existing resources in your cloud environment that were not provisioned using Terraform? This is where Terraform Import comes to the rescue. In this blog article, we will explore what Terraform Import is, why it’s valuable, and how to use it to seamlessly integrate existing resources into your Infrastructure as Code workflows.

What is Terraform Import?

Terraform Import is a command that allows you to import existing cloud resources into your Terraform state. It bridges the gap between your current resources and your Terraform configurations, enabling you to manage all your resources consistently with Infrastructure as Code.

Why is Terraform Import important?

Configuration Consistency: Terraform Import ensures that all your resources, regardless of their origin, are managed and tracked in a consistent manner. This helps avoid manual configuration drift and maintains a single source of truth for your infrastructure.

Incremental Adoption: Terraform Import allows you to incrementally adopt Terraform for existing resources. You don’t need to start from scratch, and you can gradually manage your infrastructure with Terraform without disruption.

Collaboration and Version Control: By importing resources, you can collaborate with your team using a shared version-controlled Terraform state. This enhances team collaboration and ensures everyone is working with the same infrastructure definitions.

Using Terraform Import

Step 1: Create a Terraform Configuration File

Create a Terraform configuration file (e.g., main.tf) if you haven’t already. This file should define the resource you want to import. For this example, let’s say you want to import an existing AWS EC2 instance into your Terraform configuration.

# main.tf

provider "aws" {
  region = "us-west-2" # Set your desired AWS region

resource "aws_instance" "my_instance" {
  # Define your instance configuration here

Replace the aws_instance block with the appropriate resource type and configuration for your specific use case.

Step 2: Initialize the Terraform Configuration

Navigate to the directory containing your Terraform configuration file (main.tf) in your terminal, and run the following command to initialize Terraform:

terraform init

This command initializes Terraform, downloading the necessary provider plugins.

Step 3: Import the Existing Resource

Use the terraform import command to import your existing resource. You’ll need to specify the resource type, the name you want to use for the resource in your Terraform state, and the resource identifier (ID or ARN) of the existing resource.

For example, if you want to import an existing AWS EC2 instance with the ID i-12345678 and name it my_instance, you would run:

terraform import aws_instance.my_instance i-12345678

Replace aws_instance.my_instance with the appropriate resource type and name from your main.tf file.

Step 4: Verify the Import

After running the terraform import command, Terraform will map the existing resource to the resource block in your Terraform configuration. To verify that the import was successful, you can run:

terraform show

This command will display the current state of your resources, including the imported one.

Step 5: Create Terraform Configuration for the Imported Resource

Now that the resource is imported, you should create or adjust the Terraform configuration for the imported resource in your main.tf file. This is essential to ensure Terraform can manage the resource going forward.

Make sure the configuration for the imported resource matches your desired state, including any attributes or settings you want to manage with Terraform.

Step 6: Apply the Configuration

Apply your Terraform configuration to update the resource according to your desired state:

terraform apply

Terraform will compare the configuration in your main.tf file to the existing state, and if there are any changes, it will apply them.

Challenges with the Terraform import command

The terraform import command can be a valuable tool for bringing existing resources under Terraform management. However, it also comes with some challenges and limitations:

  1. Resource Mapping: One of the primary challenges is mapping the existing resource to the appropriate Terraform resource block. You need to know the specific resource type and name in your Terraform configuration, and this mapping can sometimes be non-intuitive, especially for complex resources.
  2. Lack of Configuration: terraform import only imports the existing resource into the Terraform state; it doesn’t generate the Terraform configuration for that resource. You need to manually write or adjust the configuration for the imported resource, which can be error-prone and time-consuming.
  3. No Resource Discovery: Terraform doesn’t automatically discover all existing resources in your infrastructure. You need to know the IDs, ARNs, or other unique identifiers of the resources you want to import. In large or complex environments, this can be challenging.
  4. State Management: Importing resources can lead to issues with state management, especially if the existing resource configuration doesn’t match what’s in your Terraform configuration. Terraform may attempt to change the resource to match your configuration, potentially causing unintended consequences.
  5. Provider Limitations: Some providers may have limitations on what can be imported. Not all resources or resource attributes are importable, and this varies depending on the provider and resource type.
  6. Resource Deletion Handling: When you import an existing resource, Terraform doesn’t automatically delete it if it’s removed from your configuration. You need to manage resource deletion separately to avoid orphaned resources.
  7. No Plan Generation: Importing resources doesn’t generate a plan like creating resources from scratch does. This means you won’t get a preview of the changes before applying them, potentially leading to unexpected changes in your infrastructure.
  8. Complex Configurations: For resources with complex configurations, such as those with multiple dependencies or relationships, importing and managing them can be more challenging, as you need to ensure all dependencies are correctly represented in your Terraform configuration.
  9. Limited Provider Support: Not all Terraform providers support the terraform import command, so you might not be able to use it for certain resources or with certain cloud providers or services.
  10. Documentation and Best Practices: Finding documentation and best practices for importing specific resources can be challenging. There may be limited guidance or community knowledge on how to correctly import and manage certain resources.

Despite these challenges, terraform import is a valuable tool for incorporating existing resources into your Terraform-managed infrastructure. To overcome these challenges, it’s crucial to thoroughly understand the Terraform documentation, the specific provider’s documentation, and the resource’s configuration. Additionally, it’s a good practice to test the import process in a non-production environment first to ensure a smooth transition.

Terrraform import vs Terraformer

Terraformer and terraform import are two distinct tools and approaches used in Terraform for different purposes, primarily related to the adoption of existing infrastructure into your Terraform configuration.

Terraform Import:

  1. Purpose: terraform import is a built-in Terraform command used to import existing resources into your Terraform state and configuration. It’s typically used when you want to manage resources that were created outside of Terraform, bringing them under Terraform’s management.
  2. Resource Mapping: You need to specify the resource type and name, which you want to import, along with the ID or ARN of the existing resource. Terraform then creates a reference to this existing resource in its state file.
  3. Usage: For example, if you have an existing AWS EC2 instance with the ID “i-12345678” that you want to manage with Terraform, you can import it using:
terraform import aws_instance.my_instance i-12345678
  1. Pros:
    • It’s a direct integration within Terraform.
    • It can be used for fine-grained control of resource importing.
  2. Cons:
    • It requires manual resource mapping, which can be cumbersome for complex infrastructures.
    • It doesn’t automatically generate Terraform configuration; you must write it yourself.


  1. Purpose: Terraformer is an external tool (not a part of Terraform itself) that generates Terraform configuration for existing infrastructure resources across various cloud providers and other platforms. It’s designed to automate the process of importing existing infrastructure into Terraform.
  2. Resource Mapping: Terraformer scans your existing infrastructure, retrieves resource information, and generates Terraform configuration files that represent those resources. It maps existing resources to their Terraform equivalents.
  3. Usage: For example, you can use Terraformer to import existing AWS resources like EC2 instances, S3 buckets, and RDS databases by running a command like:
terraformer import aws --resources=aws_instance,aws_s3_bucket,aws_db_instance
  1. Pros:
    • It automates the resource discovery and Terraform configuration generation process.
    • It supports multiple cloud providers and services.
  2. Cons:
    • It’s an external tool, so it requires installation and separate configuration.
    • It may not support all resource types or custom configurations, requiring manual adjustments to the generated code.

In summary, terraform import is a manual process for importing specific resources into your Terraform state, whereas Terraformer is an automated tool for discovering and generating Terraform configurations for existing infrastructure resources. The choice between them depends on your needs and preferences, with Terraformer being more suitable for larger, existing infrastructures and terraform import for specific, manual resource management cases.

Import your terraform into Holori

Once your new resources have been inserted in your Terraform state, you can use Holori software to import the Terraform files and it will automatically create a terraform diagram of your infra.

From there you can now visualize your entire infra, the various elements and their attributes. By doing so, it becomes much easier to ensure that no resource is left aside and that you fully understand how resources are related to another.

visualize terraform import

Alternatively you can use Holori to scan your AWS account with read only permissions and Holori will generate a diagram and the terraform code for all the imported resources.

Start visualizing your terraform now: https://app.holori.com/register

To conclude

Terraform Import is a powerful feature that allows you to seamlessly integrate existing resources into your Infrastructure as Code workflows. By importing resources, you can manage your entire infrastructure consistently, regardless of its origin, and enjoy the benefits of collaboration, version control, and automation that Terraform provides. Combine it with Holori to make sure that you visualize your entire infra and that there is no blind spot. So, embrace the versatility of Terraform Import and bring all your resources under the umbrella of Infrastructure as Code with ease. Happy importing!

Share This Post

Subscribe To Our Newsletter

Get updates and learn from the best

More To Explore