Import existing infrastructure

You created a storage bucket by hand months ago, and now you want Terraform to own it without tearing it down and rebuilding. The original tool for that is terraform import^[1], the command that binds one already-existing remote object to a resource address in your configuration by recording it in Terraform state^[2]. It changes nothing in the real world: it only teaches Terraform that the object exists and which address manages it from now on. This section covers the command's two positional arguments, why the target resource block has to exist before you run it, and the fact that import writes only to state.

Write the resource block first

The command takes exactly two positional arguments:

terraform import ADDRESS ID

ADDRESS is the resource address^[3] in your configuration, such as aws_s3_bucket.assets, and ID is the provider's own identifier for the real object, such as the bucket name. The ID format is defined by the resource type, not chosen by Terraform, so each resource type's documentation states what its import ID looks like.

Because the command binds an object to an address, that resource block must already exist. Importing via the CLI does not generate configuration^[4]: point terraform import at an address with no matching resource block and it fails. The normal routine is to write a skeleton resource block, run the import, then run terraform plan and fill in arguments until the plan reports no changes, which is the signal that your configuration now matches the imported object.

It only writes state

terraform import can only import resources into state^[4]. It does not create, update, or destroy real infrastructure, and it does not write any HCL for you. It also imports one object per invocation, so adopting ten objects means running the command ten times. There is no provider-specific variant such as terraform import-aws, and terraform refresh^[5] does not help either: refresh only reconciles state for resources Terraform already manages and never discovers or adopts an unmanaged object.

Running one CLI command per object does not fit code review or a large migration, so Terraform 1.5 introduced the import block^[6]: a way to declare imports in configuration and run them through the ordinary workflow. An import block names where the object goes and what it is.

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

to and id

The to argument^[7] is the resource address to import into, and the id argument is the cloud provider's identifier for the existing object. Do not swap them: to is the Terraform address, id is the real object's provider ID. The id must be a string or an expression that is known at plan time^[7], so it can reference an input variable but cannot depend on a value that is only known after apply. A single block imports one object; adding for_each^[7] to the block imports a whole map or set of similar objects without a separate block for each.

Plan and apply, then delete the block

An import block runs through the normal plan and apply workflow^[6]: terraform plan shows the import alongside any other planned changes, and terraform apply carries it out. There is no separate import subcommand. Like the CLI command, the import block only affects state; the real object is untouched. By default the to address must still match a resource block you have written, so the one way to skip writing that block first is configuration generation, covered in the next section. Because the block does nothing once the object is in state, you can remove it after a successful apply^[6] without destroying the resource, and the common practice is to delete import blocks once the migration is done so the configuration is not cluttered with one-time instructions.

Writing the resource block by hand is the tedious part of an import, especially for a resource with dozens of arguments. The config-driven path can produce a first draft for you: run terraform plan -generate-config-out=FILE^[8] with an import block whose to points at a resource that does not yet exist in your configuration, and Terraform writes generated HCL for that object into the named file.

A plan-time feature of import blocks, not the CLI

Configuration generation is a feature of import blocks reached through terraform plan; the classic terraform import CLI command cannot generate configuration^[4]. The FILE must be a new path: supplying a path to an existing file makes Terraform error^[8] rather than overwrite your work. Once the plan has written the file, terraform apply completes the import.

Review before you apply

The output is Terraform's best guess at the value for each resource argument^[8]: a template to iterate on by removing some attributes, adjusting the value of others, and rearranging blocks, not a finished module. For some resources Terraform cannot construct a valid configuration and emits blocks that need manual fixes, and not every provider supports generation. Review and edit the generated file before you apply it.

Import questions turn on a few sharp distinctions between the two mechanisms. Match the stem to the mechanism.

• A stem says import will write the configuration for you. That is false for the CLI: terraform import only updates state, so the resource block must already exist. Configuration generation is a feature of the config-driven import block via terraform plan -generate-config-out=FILE, not of the classic command.
• A stem asks how to import many resources, or to keep imports in version control and code review. The answer is import blocks, not a loop of CLI commands: blocks are declarative, reviewable, and support for_each, whereas terraform import imports one object per invocation.
• A stem swaps to and id, or asks which is which. to is the Terraform resource address; id is the provider's own identifier for the existing object, and its format is set by the resource type.
• A stem invents a command like terraform import-gcp, or claims terraform refresh adopts unmanaged resources. Both are wrong. The only ways to bring existing infrastructure under management are terraform import ADDRESS ID and the import block; refresh only updates resources already in state.
• A stem asks whether you can delete an import block afterward. Yes. An import block only affects state, so removing it after a successful apply does not destroy the resource.
• A stem treats generated configuration as ready to apply. It is a starting point: review and edit it first, because generated blocks may include attributes that need adjustment to produce a clean plan.