Import blocks

An import block brings an existing infrastructure object under Terraform management. The object was created outside of Terraform — manually, by a script, or by another tool — and the import block tells Terraform to adopt it into state instead of creating a new one.

  flowchart LR
    existing["Existing object<br/>(created outside Terraform)"] -- "import block" --> state["Terraform state"]
    config["resource block"] --> state

An import block has two required arguments: to (the resource address in your configuration) and id (the provider-specific identifier of the existing object):

1
2
3
4
5
6
7
8

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

resource "aws_s3_bucket" "assets" {
  bucket = "my-existing-bucket"
}

Run terraform plan to preview the import — Terraform shows the object will be imported rather than created:

aws_s3_bucket.assets: Preparing import... [id=my-existing-bucket]

Plan: 1 to import, 0 to add, 0 to change, 0 to destroy.

Running terraform apply records the object in state. Because imports are part of the plan, they are reviewable in pull requests and CI pipelines — unlike the older terraform import CLI command, which modified state immediately with no preview.

If you have not yet written the resource block, Terraform can generate it for you:

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

Review and clean up the generated configuration before applying.

Best practices

• Prefer import blocks over the terraform import CLI command — they are declarative, previewable in terraform plan, and reviewable in version control.
• Use -generate-config-out as a starting point, but always review and simplify the generated configuration.
• Verify the plan shows no changes (only the import) before applying — unexpected changes mean your configuration does not match the real object.
• Remove import blocks after they have been applied to keep your configuration tidy.