Import block syntax (Terraform 1.5+) - Deep Dive

Overview - Import block syntax (Terraform 1.5+)

What is it?

The import block syntax in Terraform 1.5+ is a new way to bring existing cloud resources into Terraform's management. Instead of running separate commands, you declare imports directly in your configuration files. This makes importing more transparent, repeatable, and part of your infrastructure code. It helps Terraform understand and track resources you already have without recreating them.

Why it matters

Without import blocks, managing existing resources was manual and error-prone, requiring separate commands outside your code. This could lead to drift, confusion, or accidental resource duplication. Import blocks solve this by making imports part of your code, so your infrastructure state and configuration stay in sync. This improves safety, collaboration, and automation in managing cloud resources.

Where it fits

Before learning import blocks, you should understand basic Terraform concepts like resources, state, and the CLI import command. After mastering import blocks, you can explore advanced state management, automation pipelines, and Terraform modules that use imports for complex infrastructure setups.

Mental Model

Core Idea

Import blocks let you declare existing resources inside your Terraform code so Terraform can manage them without recreating.

Think of it like...

It's like adding a new item to your home inventory list by writing it down, instead of searching the whole house every time you want to check what you own.

┌─────────────────────────────┐
│ Terraform Configuration File │
│ ┌─────────────────────────┐ │
│ │ resource "aws_s3_bucket"│ │
│ │   "my_bucket" {         │ │
│ │   ...                   │ │
│ │ }                       │ │
│ └─────────────────────────┘ │
│ ┌─────────────────────────┐ │
│ │ import {                │ │
│ │   id = "bucket-name"   │ │
│ │   to = aws_s3_bucket.my_bucket │
│ │ }                       │ │
│ └─────────────────────────┘ │
└─────────────────────────────┘

Build-Up - 7 Steps

1

Foundation

Terraform resource basics

Concept: Understand what a Terraform resource is and how it is declared.

In Terraform, a resource represents a cloud or infrastructure object, like a server or database. You declare it in your configuration with a type and a name, then specify its settings. For example, an AWS S3 bucket resource looks like this: resource "aws_s3_bucket" "my_bucket" { bucket = "my-unique-bucket-name" acl = "private" } This tells Terraform to create and manage an S3 bucket with the given name and access control.

Result

Terraform knows what resource to create or manage when you run commands.

Understanding resources is key because import blocks connect existing resources to these declarations.

2

Foundation

Terraform state and import command

Concept: Learn how Terraform tracks resources and how the import command works.

Terraform keeps a state file that records what resources it manages and their current settings. When you create resources with Terraform, it updates this state. But if you have existing resources created outside Terraform, you need to tell Terraform about them. The terraform import command lets you link an existing resource to a Terraform resource declaration by specifying the resource address and the real resource ID. Example: terraform import aws_s3_bucket.my_bucket my-unique-bucket-name This imports the existing S3 bucket into Terraform's state.

Result

Terraform state now includes the existing resource, so it won't try to recreate it.

Knowing how import works manually sets the stage for understanding the new import block syntax.

3

Intermediate

Introduction to import block syntax

🤔Before reading on: do you think import blocks replace the import command or just complement it? Commit to your answer.

Concept: Import blocks let you declare imports inside Terraform configuration files, making imports part of the code.

Starting with Terraform 1.5, you can write import blocks inside your .tf files. This means you no longer need to run terraform import commands manually. Instead, you declare which existing resources to import, and Terraform will handle it during apply or plan. Example: import { id = "my-unique-bucket-name" to = aws_s3_bucket.my_bucket } This tells Terraform to import the resource with the given ID into the specified resource address.

Result

Terraform automatically imports the resource during plan or apply, keeping state and config in sync.

Understanding that imports can be declared as code improves automation and reduces manual errors.

4

Intermediate

Syntax details and usage rules

🤔Before reading on: do you think import blocks can import multiple resources at once or only one per block? Commit to your answer.

Concept: Learn the exact syntax rules and limitations of import blocks.

Each import block imports exactly one resource. You can have multiple import blocks for multiple resources. The block requires two fields: - id: the real resource identifier in the cloud - to: the Terraform resource address to import into Example with multiple imports: import { id = "bucket-1" to = aws_s3_bucket.bucket_one } import { id = "bucket-2" to = aws_s3_bucket.bucket_two } Import blocks must be placed at the top level in your configuration, not nested inside resources or modules.

Result

You can manage multiple imports declaratively and clearly in your code.

Knowing the syntax prevents common mistakes and helps organize imports cleanly.

5

Intermediate

Import blocks and Terraform lifecycle

🤔Before reading on: do you think import blocks run every time you apply or only once? Commit to your answer.

Concept: Understand when import blocks execute and how they affect Terraform runs.

Import blocks run during terraform plan and apply phases. If the resource is not yet in state, Terraform imports it automatically. If already imported, Terraform skips re-importing. This means import blocks are idempotent and safe to keep in your code permanently. This contrasts with the manual import command, which you run once outside Terraform. Import blocks also integrate with Terraform's dependency graph, so imports happen before resource updates.

Result

Terraform manages imports smoothly as part of its normal workflow without extra commands.

Understanding lifecycle integration helps avoid confusion about when imports happen and ensures smooth automation.

6

Advanced

Import blocks with modules and complex setups

🤔Before reading on: do you think import blocks can import resources inside modules directly? Commit to your answer.

Concept: Learn how import blocks work with modules and nested resources.

Import blocks can import resources inside modules by specifying the full resource address including module paths. Example: import { id = "resource-id" to = module.my_module.aws_s3_bucket.my_bucket } This imports the resource into the module's resource. However, the module must already be declared in your configuration. Import blocks cannot import resources created by modules that are not yet instantiated or dynamic resources created by count or for_each without exact addresses.

Result

You can manage imports in modular infrastructure but must carefully specify addresses.

Knowing module import limitations prevents errors in complex Terraform projects.

7

Expert

Advanced import block internals and edge cases

🤔Before reading on: do you think import blocks update resource attributes automatically after import? Commit to your answer.

Concept: Explore how import blocks interact with state refresh, attribute updates, and edge cases.

When Terraform imports a resource via an import block, it fetches the current state from the provider and updates the Terraform state accordingly. However, import blocks do not modify your configuration files; they only update state. If the imported resource's attributes differ from your config, Terraform will plan to update them unless you adjust your config. Edge cases include resources with complex IDs, resources that require special import syntax, or resources that change IDs after import. Import blocks rely on the provider's import support. Also, import blocks do not support importing multiple IDs into a single resource with count or for_each; you must declare separate import blocks.

Result

You gain precise control over imports but must manage config-state drift carefully.

Understanding import internals helps avoid surprises and manage state drift effectively.

Under the Hood

Terraform's import block syntax is parsed during the configuration phase. When Terraform plans or applies, it checks if the resource specified in the import block exists in the state. If not, Terraform calls the provider's import function with the given ID to fetch the resource's current state and adds it to the Terraform state file. This process integrates with Terraform's dependency graph, ensuring imports happen before resource updates. Import blocks do not alter configuration files; they only affect the state. Terraform then compares the imported state with the configuration to plan any necessary changes.

Why designed this way?

Import blocks were introduced to solve the problem of manual, error-prone imports outside Terraform code. By making imports declarative, Terraform improves automation, repeatability, and collaboration. The design keeps imports separate from resource declarations to avoid confusion and maintain clear separation of concerns. It also leverages existing provider import mechanisms to avoid reinventing import logic. Alternatives like embedding import IDs inside resources were rejected to keep resource declarations clean and focused on desired state.

┌───────────────────────────────┐
│ Terraform Configuration Parser │
└───────────────┬───────────────┘
                │
                ▼
       ┌───────────────────┐
       │ Import Block Found │
       └─────────┬─────────┘
                 │
                 ▼
       ┌───────────────────┐
       │ Check State File   │
       └─────────┬─────────┘
                 │
      ┌──────────┴──────────┐
      │                     │
      ▼                     ▼
┌───────────────┐    ┌─────────────────┐
│ Resource in   │    │ Resource Missing │
│ State?        │    │ in State         │
└──────┬────────┘    └─────────┬───────┘
       │                       │
       ▼                       ▼
No action needed       Call Provider Import
       │                       │
       ▼                       ▼
Continue Plan/Apply    Update State File
                │
                ▼
       ┌───────────────────┐
       │ Compare State and  │
       │ Configuration     │
       └───────────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Do import blocks replace the terraform import CLI command completely? Commit to yes or no.

Common Belief: Import blocks completely replace the need for the terraform import command.

Reality: Import blocks automate imports during plan/apply but do not replace the CLI import command in all cases. Some complex or one-time imports still require manual CLI use.

Why it matters: Assuming import blocks replace CLI import can lead to confusion when imports fail or when advanced import scenarios require manual intervention.

Quick: Do import blocks modify your Terraform resource configuration automatically? Commit to yes or no.

Common Belief: Import blocks update your resource configuration to match the imported resource automatically.

Reality: Import blocks only update Terraform state, not configuration files. You must manually adjust configuration to match imported resource attributes if needed.

Why it matters: Believing configuration updates happen automatically can cause unexpected plan changes and drift.

Quick: Can one import block import multiple resources using count or for_each? Commit to yes or no.

Common Belief: One import block can import multiple resources using count or for_each expressions.

Reality: Each import block imports exactly one resource. To import multiple resources, you need multiple import blocks.

Why it matters: Trying to import multiple resources with one block leads to errors and confusion.

Quick: Do import blocks run only once or every time you run terraform apply? Commit to once or every time.

Common Belief: Import blocks run only once and then never again.

Reality: Import blocks run during every plan and apply, but if the resource is already in state, Terraform skips re-importing.

Why it matters: Misunderstanding this can cause confusion about when imports happen and lead to redundant manual imports.

Expert Zone

1

Import blocks do not affect resource lifecycle hooks like create_before_destroy or prevent_destroy, so imported resources still follow normal lifecycle rules.

2

Import blocks rely entirely on provider import support; if a provider lacks import functionality for a resource, import blocks cannot be used for that resource.

3

Import blocks can cause subtle state drift if the configuration does not exactly match the imported resource's attributes, requiring careful state and config alignment.

When NOT to use

Avoid import blocks when importing resources that require complex or custom import logic not supported by the provider. In such cases, use the terraform import CLI command manually. Also, do not use import blocks for one-off imports in ephemeral environments where manual import is simpler.

Production Patterns

In production, teams declare import blocks in version-controlled Terraform code to automate onboarding of existing infrastructure. They combine import blocks with CI/CD pipelines to ensure state consistency. Import blocks are often used alongside modules to manage imported resources in large, modular infrastructures.

Connections

Infrastructure as Code (IaC)

Import blocks build on the IaC principle of declaring infrastructure in code.

Knowing import blocks deepens understanding of how IaC can manage not just new but existing resources declaratively.

Version Control Systems

Import blocks integrate imports into code that lives in version control.

This connection shows how infrastructure changes, including imports, become auditable and repeatable like software code.

Inventory Management

Import blocks are like adding items to an inventory list to track assets.

Understanding inventory management helps grasp why declaring imports in code improves tracking and reduces surprises.

Common Pitfalls

#1 Trying to import multiple resources with one import block.

Wrong approach:

import {
id = ["id1", "id2"]
to = aws_s3_bucket.my_bucket
}

Correct approach:

import {
id = "id1"
to = aws_s3_bucket.bucket_one
}
import {
id = "id2"
to = aws_s3_bucket.bucket_two
}

Root cause:

Misunderstanding that each import block handles only one resource.

#2 Expecting import blocks to update resource configuration automatically.

Wrong approach:

Relying on import block alone without adjusting resource attributes in configuration after import.

Correct approach:

Manually update resource configuration to match imported resource attributes after import block runs.

Root cause:

Confusing state updates with configuration changes.

#3 Placing import blocks inside resource or module blocks.

Wrong approach:

resource "aws_s3_bucket" "my_bucket" {
import {
id = "bucket-name"
to = aws_s3_bucket.my_bucket
}
}

Correct approach:

import {
id = "bucket-name"
to = aws_s3_bucket.my_bucket
}

Root cause:

Not knowing import blocks must be top-level blocks in configuration.

Key Takeaways

Import blocks let you declare existing resources inside Terraform code for automated, repeatable imports.

They improve safety and collaboration by making imports part of your infrastructure as code.

Each import block imports exactly one resource and must be top-level in your configuration.

Import blocks update Terraform state but do not modify resource configuration files.

Understanding import blocks helps manage complex infrastructure with less manual effort and fewer errors.