Importing Existing Infrastructure

What it is

Importing brings a resource that already exists, created by hand or by another tool, under Terraform management. After the import, the object is recorded in state at a resource address and Terraform plans changes to it like any other resource.

Terraform offers two ways to do it: the import block, which is part of configuration and goes through plan and apply, and the older terraform import command, which writes straight to state.

How it works

The import block

An import block names the resource address to import into (to) and the provider's ID for the real object (id).

import {
  to = aws_s3_bucket.logs
  id = "acme-app-logs"
}

resource "aws_s3_bucket" "logs" {
  bucket = "acme-app-logs"
}

The ID format depends on the resource type. A bucket name, an instance ID or a full Azure resource ID are all common, and each resource's documentation in the registry describes its import ID.

What plan and apply do

terraform plan shows the resource as "will be imported" along with any changes needed to match the configuration. Nothing is imported until you run terraform apply. If the configuration differs from the real object, the same apply also makes those changes, so read the plan carefully.

After a successful import you can delete the import block or keep it as a record. Keeping it is harmless because the object is already in state.

Generating configuration

Writing the resource block by hand is slow for resources with many arguments. Terraform can write it for you from the import block.

import {
  to = aws_instance.web
  id = "i-0abc123def4567890"
}

terraform plan -generate-config-out=generated.tf

Terraform reads the real object and writes a resource block for every import block that has no matching resource block. The docs still label configuration generation as experimental.

Once the generated file plans cleanly, run terraform apply to finish the import and treat the file as normal configuration.

The terraform import command

terraform import aws_instance.web i-0abc123def4567890

The command takes a resource address and an ID and writes the object into state immediately. Compare it with the import block:

Apart from generated configuration, neither method writes resource blocks. Every imported object needs one that matches it.

Import safety

Import each real object to only one resource address. If two addresses, or two configurations, manage the same object, each run fights the other. Importing also does not change the real resource by itself; only differences you approve in the plan do.

How the exam asks about this

• "You must bring 20 existing buckets under management and review the result first." Use import blocks (with for_each or several blocks) and review the plan.
• "You have an import block but no resource block and want Terraform to write it." Run terraform plan -generate-config-out=FILE.
• "Does terraform import create the resource block for you?" False; it only writes state, so the block must exist.