Import block syntax (Terraform 1.5+) - Commands & Configuration

Introduction

Sometimes you have existing resources created outside Terraform and want to manage them with Terraform. The import block syntax in Terraform 1.5+ lets you declare these imports inside your configuration, so Terraform knows about them before you apply changes.

When you have a cloud resource created manually and want Terraform to manage it without recreating it.

When you want to keep your Terraform state in sync with resources created by other teams or tools.

When migrating existing infrastructure to Terraform management gradually.

When you want to automate importing resources as part of your Terraform workflow.

When you want to avoid running separate import commands manually.

Config File - main.tf

main.tf

terraform {
  required_version = ">= 1.5"
}

resource "aws_s3_bucket" "example" {
  bucket = "my-example-bucket"
  acl    = "private"
}

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

This Terraform file defines an AWS S3 bucket resource named example. The import block tells Terraform to link the existing S3 bucket named my-example-bucket to this resource in the state. This way, Terraform knows it manages this bucket without creating a new one.

The terraform block ensures the Terraform version is 1.5 or higher, which supports the import block syntax.

Commands

This command initializes the Terraform working directory, downloads necessary providers, and prepares Terraform to run.

Terminal

terraform init

Expected Output

Initializing the backend...



Initializing provider plugins...

- Finding latest version of hashicorp/aws...

- Installing hashicorp/aws v4.0.0...

- Installed hashicorp/aws v4.0.0 (signed by HashiCorp)



Terraform has been successfully initialized!



You may now begin working with Terraform. Try running "terraform plan" to see any changes.

This command shows what Terraform will do. Since the import block links an existing resource, Terraform will not try to create or destroy it.

Terminal

terraform plan

Expected Output

No changes. Infrastructure is up-to-date.



This means that Terraform did not detect any changes to apply.

This command applies the configuration. Because the resource is imported, Terraform will manage it without creating or deleting it.

Terminal

terraform apply -auto-approve

Expected Output

aws_s3_bucket.example: Refreshing state... [id=my-example-bucket]



Apply complete! Resources: 0 added, 0 changed, 0 destroyed.

→

-auto-approve - Automatically approves the apply without asking for confirmation

Key Concept

If you remember nothing else, remember: the import block in Terraform 1.5+ lets you declare existing resources inside your config so Terraform manages them without manual import commands.

Common Mistakes

Not specifying the correct resource address in the import block's 'to' field.

Terraform won't link the existing resource correctly, causing errors or attempts to recreate the resource.

Use the exact resource name and type as declared in your Terraform configuration for the 'to' field.

Using Terraform version below 1.5 which does not support import blocks.

Terraform will fail to parse the import block and show syntax errors.

Ensure Terraform version is 1.5 or higher by setting 'required_version' in the terraform block and upgrading Terraform.

Not running 'terraform init' before 'terraform plan' or 'apply'.

Terraform won't have the necessary providers and setup, causing errors.

Always run 'terraform init' first to prepare the working directory.

Summary

Write an import block in your Terraform config to link existing resources to Terraform state.

Run 'terraform init' to prepare your environment before planning or applying.

Use 'terraform plan' to verify no unexpected changes will happen.

Apply with 'terraform apply' to start managing the imported resource.